Content of AuroraWatch UK API v1.0

[stevemarple]

I'm generating a list of the information that should included in the v1.0 AuroraWatch UK API. So far I have:

• Threshold list
  • Threshold
    • Status level
    • Lower limit (and upper limit?)
    • Color with RGB values
• Activity list
  • Start time
  • Status level
  • Value
• Station list (list of magnetometers used to compute the current status)
  • Station/instrument/magnetometer
    • Project (eg. AURORAWATCHNET, SAMNET)
    • Site (eg. LAN1)
• Current status
  • Status level
• Previous status
  • Status level
• Creation time
• Status message
  • Message text
  • Issued (ISO8601 datetime)
  • Time-to-live (TTL, in seconds)

If the status message is present, and its message text is not empty, this provides a message which could be presented (silently?) to the user, eg, "System down due to maintenance", "Aurora sighted from Cornwall!". The message should not be displayed after the TTL has expired. If implemented the app is responsible for ensuring the message is not displayed multiple times.

The nested list hints at how the XML document is likely to be structured. The list of stations will be fairly static so I think that is perhaps best left to a separate document to minimise the data transferred. See issue #5 for details.

As much as I hate American spellings I will use "color" since that is the spelling used in HTML/CSS.

[stevemarple]

Alerts are reissued if the activity level remain elevated for more than 12 hours (24 for email). At present no distinction is made but it would be nice if some indication could be made. This has implications on how the current and previous status should be handled (depending upon implementation that might affect the app, the server or both).

[neilmorton]

@stevemarple I would suggest that the station list needs only to contain the station id (i.e. awn_lan1). The lookup for any other info would be via the other api, which we should really only need to call say once every 7 days just to ensure that we have the latest data, and store locally in the app for use in-between.

Another point to link with the Threshold list is any future latitudinal lines you may want to define these thresholds. If these were a fixed latitude, this would sit nicely here. However, if they are screwed lines to match with the tilts, it may well be that this Threshold data may itself warrant splitting out into another API to be called say every 7 days, to avoid data bloat on the frequently required API.

[stevemarple]

Status message should define message text, an issued date/time and a time-to-live. Apps should stop displaying the message when the TTL has expired.

[neilmorton]

@stevemarple In relation to the message text, whilst the actual size on Apple can be just over 2,000 characters, to be able to see the whole message in the notification centre on pre iPhone 6 models, they can be up to 110 characters. This will however truncate on pre iPhone 6 banner (if the phone is in use and it pops up at the top), if you wish to remain within viewable area here, it can be up to 65 characters.

I would therefore suggest a maximum of 110 characters, but if / where possible try to keep messages to 65 characters.

[stevemarple]

Information split into an activity XML file and another file containing the list of sites with attribution etc (thanks @progressconcepts for the idea).

Initial sample versions of the XML files added.

[stevemarple]

I don't think the previous status serves any real purpose. Every instance of an app will need to remember the last time it issued a notification, and only issue a new notification if the current state is more active, or some timeout period has elapsed. My AuroraWatch app parses it and prints it for debugging but never actually uses it. I plan to remove previous status unless convinced otherwise.

[neilmorton]

@stevemarple I am happy with the removal of the previous status. I can't see any reason for it, as, like you say, we can manage this from our side.

[jpsingleton]

The data content looks fine to me. I have some ideas about the transport though.

Could the new API please have cross origin headers? This allows access from web pages, client side with JavaScript. Having a JSON option would be nice but XML is OK.

Have a look at my rail API project if you want a better idea of what I mean.