Swift Target-of-Opportunity API

Introduction to the API

API Version 2 (swifttools 4.0+)

Author: Jamie A. Kennea (Penn State)

Introduction

The following gives an explanation of how the Swift TOO API works, and how API queries are formatted. Beginning with swifttools 4.0, the API has been redesigned as a modern RESTful service. If you are not interested in using the API at the low level, we suggest that you skip this section and move onto the documentation for and examples of how to use the swift_too Python module.

Base URL

All API v2 endpoints are rooted at:

https://www.swift.psu.edu/api/v2

For example, the visibility query endpoint is available at /api/v2/swift/visquery/.

Authentication

The v2 API uses session-based authentication via a browser cookie (session). There is no longer a shared-secret JWT — instead, you authenticate once by POSTing your credentials (username plus either your account password or an API key) to the /login endpoint and then include the returned session cookie in all subsequent requests.

Logging in

POST /api/v2/login

Send a JSON body containing your username and password. If you are using an API key instead of your account password, supply the API key in the password field; the field name is retained for historical reasons:

{
  "username": "myuser",
  "password": "my_api_key_or_password"
}

A successful login returns HTTP 200 and sets a session cookie that must be supplied with every subsequent authenticated request. Most HTTP clients (e.g. Python's requests.Session) handle this automatically.

Logging out

POST /api/v2/logout

Invalidates the current session. No request body is required.

Checking session status

GET /api/v2/session

Returns the username associated with the current session:

{
  "username": "myuser"
}

Alternative: API-key login

POST /api/v2/login/password

Accepts the same LoginData body as /login and can be used when authenticating via an API key instead of a password.

Request format

Requests are standard HTTP calls. Query parameters (for GET requests) are passed as URL query strings, and request bodies (for POST requests) use either application/json or application/x-www-form-urlencoded encoding depending on the endpoint. There is no longer any JWT wrapping of request data.

Example – Swift visibility query

GET /api/v2/swift/visquery/?ra=195.699&dec=-63.836&length=28

Required parameters: ra, dec. Optional: begin, end, length, hires.

A successful response (HTTP 200) returns a JSON object directly:

{
  "begin": "2021-02-18T00:00:00",
  "length": 28.0,
  "ra": 195.699,
  "dec": -63.836,
  "hires": false,
  "windows": [
    {
      "begin": "2021-02-21T00:33:00",
      "end": "2021-04-07T07:21:00"
    }
  ],
  "status": {
    "status": "Accepted",
    "too_id": null,
    "jobnumber": null,
    "errors": [],
    "warnings": []
  }
}

Response format

All successful responses return a JSON object whose fields correspond to the schema of the requested resource. Error responses return an HTTP error status code together with a SwiftTOOStatusSchema JSON body:

{
  "status": "Error",
  "too_id": null,
  "jobnumber": null,
  "errors": ["Descriptive error message"],
  "warnings": []
}

HTTP status codes

No queue system

Unlike the v1 API, the v2 API is synchronous — responses are returned immediately and there is no job queue to poll. The jobnumber field in status objects is retained for backwards compatibility but is not used in v2.

Available endpoints

Endpoints are grouped below by functional area. All paths are relative to /api/v2.

Health Check

Authentication

Swift Schedules

Swift Visibility

Swift Target-of-Opportunity

Swift Clock

Swift UVOT

Swift Data

GUANO

Swift Operations (admin)

NICER

Utilities

Backwards Compatibility

Submitting a TOO request

TOO requests are submitted by POSTing to /api/v2/swift/too with an application/x-www-form-urlencoded body. Required fields are:

Optional fields include urgency (0–4, default 3), instrument (XRT, UVOT, or BAT, default XRT), xrt_mode, uvot_mode, tiling, num_of_visits, monitoring_freq, and many others documented in the SwiftTOOPostSchema.

A successful submission returns HTTP 201 and a SwiftTOOStatusSchema body containing the assigned too_id.

Moving forward

We strongly recommend using the supplied Python implementation of the API (swifttools 4.0+). This abstracts the REST calls above and provides a simple, Pythonic interface to the TOO API. Please review the documentation for the Python API and the examples available as Jupyter Notebooks.