Swift TOO API - API Format

Introduction to the API

API Version 1.2

Author: Jamie A. Kennea (Penn State)

Introduction

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.

API format

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 epoch
• dec - The declination in the same format
• begin - 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.

Moving forward

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.