The following gives an explanation of how the API works, and how API queries are formatted. If you are not interested in using the API at the low level, we suggest that at this point, you skip this and move onto the documentation for and examples of how to use the swift_too
Python module.
Submissions to to the Swift TOO API are formatted utilizing a simple JSON format, and transmitted as JSON Web Tokens (https://jwt.io) which are signed using a 'shared secret' key. The JSON format is simple, and can be constructed utilizing any software. The format in JSON consists of the following structure, here an example of a Swift_VisQuery
request, which requests the visibility of :
{"api_name": "Swift_VisQuery",
"api_version": "1.2",
"api_data": {"username": "username",
"ra": 195.698559054,
"dec": -63.835729423017,
"begin": "2021-02-18 00:00:00",
"length": 28.0,
"windows": []}}
There are three top level components to the JSON: api_name
which gives the name of the type of request being made. The options here are Swift_VisQuery
for requesting Visibility, Swift_AFST
for requesting observation information and Swift_TOO_Request
for submitting a Swift TOO. The next is api_version
which gives the version of the API you are using. It is expected that API versions will change over time as new features are added, so it's important to specify the version of the API you are using. The current version is 1.2. Lastly is api_data
, which includes the parameters passed to the TOO_API. In the case of the Swift_VisQuery
above is a complete set of parameters. Which are:
username
- The username of the requester.ra
- The Right Ascension in decimal degrees and J2000 epochdec
- The declination in the same formatbegin
- The start time of the requested observation window in a standard 'YYYY-MM-DD HH:MM:SS' format in UTC timezone.length
- the number of days to calculate the visibility over.windows
- optional, but this is the array in which the results of the query will be returned.This JSON must be encoded and signed into JWT format using the 'shared secret', a passphrase that both the user and the Swift TOO API server knows. In this case, if we assume the shared secret is 'mysharedsecret' the JWT will be as follows
In order to submit this request, a simple HTML request is sent utilizing the above JWT. You can either submit utilizing POST or GET. The GET form represents the simpliest way to illustrate this, as the TOO API submission becomes a URL that can be entered into any browser.
The result of this URL will be one of two things, either you will be echoed back the JSON structure above, with results filled out, or you will get a Swift_TOO_Status
JSON, which is sent to inform that the job is not yet complete. Here is an example of a the successful result of the above URL:
{"api_name": "Swift_VisQuery",
"api_version": "1.2",
"api_data": {
"username": "myuser",
"ra": 195.69856,
"dec": -63.83573,
"begin": "2021-02-18 00:00:00",
"length": 28,
"windows": [
{"api_name": "Swift_VisWindow",
"api_version": "1.2",
"api_data": {
"begin": "2021-02-21 00:33:00",
"end": "2021-04-07 07:21:00"}
}],
"status": {
"api_name": "Swift_TOO_Status",
"api_version": "1.2",
"api_data": {
"status": "Accepted",
"too_id": null,
"jobnumber": 1111,
"errors": [],
"warnings": []
}
}
}
}
The above result shows how results are structured. In this case, we care about visibility windows. These are giving in the api_data:windows
parameter, which itself is an array of Swift_VisWindow
structures. These have the same structures as the top level result, this case, the api_data
of a Swift_VisWindow
object as two parameters, begin
and end
, the start and stop of the visibility window. In addition we see the status
parameter which contains the Swift_TOO_Status
object. This shows the status of the request, in this case, Accepted. In the case of a job being stilled Queued, Processing or Rejected, a Swift_TOO_Status
object is returned only.
As the TOO API works on a Queue system, first in/first out. It is common that immediately a request will return either Queued or Processing. As the requests are cached, in order to determine the current status of the job, the URL simply needs to be submitted again, or in a web browser, hit reload. In addition the status or jobs, which are identified by the jobnumber
parameter in Swift_TOO_Status
can be fetched by sending a Swift_TOO_Status
request. In this case, the parameters are simply username
and jobnumber
, e.g.:
{"api_name": "Swift_TOO_Status",
"api_version": "1.2",
"api_data": {
"username": "username",
"jobnumber": 1111,
}
}
which turns into:
Note that although URL submission (i.e. HTTP POST) of jobs is easiest to visualize and do by hand, the Python API internally defaults to HTTP POST to submit to the API. The reason for this is simple, complex queries can generate URLs that are too long for some browsers to handle, whereas using POST to submit circumvents this. Both GET (i.e. URL encoded arguments) and POST work, but if possible POST is recommended.
Submitting this will return the status of jobnumber
1111. If the argument fetchresult
is added to the above JSON, then the return will include a result
parameters, which will contain the result of the job processing, in this case, the Swift_VisQuery
JSON above. Which would look like this:
{"api_name": "Swift_TOO_Status",
"api_version": "1.2",
"api_data": {
"username": "myuser",
"status": "Accepted",
"jobnumber": 1111,
"errors": [],
"warnings": [],
"timestamp": "2021-03-15 22:18:07",
"began": "2021-03-15 22:18:07",
"completed": "2021-03-15 22:18:07",
"fetchresult": True,
"result": {
"api_name": "Swift_VisQuery",
"api_version": "1.2",
"api_data": {
"username": "myuser",
"ra": 266.4168,
"dec": -29.0078,
"begin": "2021-03-15 22:18:05.963483",
"length": 1,
"hires": False,
"windows": [{
"api_name": "Swift_VisWindow",
"api_version": "1.2",
"api_data": {
"begin": "2021-03-15 22:18:00",
"end": "2021-03-16 22:18:00"
}
}]
}
}
}
}
The takeaway here is that the API structure is standard, and can be nested. Therefore an API structure can be a parameter in another one. So in the case above, the request is a Swift_TOO_Status
, which has a parameter result
, which itself is a Swift_VisQuery
object, for which the data consists of Swift_VisWindow
objects.
This structure allows complex data structures to be embedded within arguments to both requests and results.
We strongly recommend that the you use the supplied Python implementation of the API. This abstracts most of the above, and allows for simple interaction with the TOO API. Please review the documentation for the Python API implementation, and the examples given, which are also available as Jupyter Notebooks.