Solver REST API App

Overview

In addition to the console Solver App, the REST API app is provided as an alternative means to provide the solver as a service. The API is a .NET 6 Web API project, published as a single self-contained executable. It's as easy to run as the console solver. Once you run it, it starts to serve the REST API, accepts requests and queues and executes solves.

The API was created for two main purposes:

1. To enable using the solver by a group/community, with the solver running on one machine and many users running solves on it. There's at least some demand for such a thing, which made it worth spending the effort to provide it.
2. To provide a compatibility layer so that the solver can be immediately adopted without having to make changes to existing software. The Astrometry.net online solver (nova.astrometry.net) is already supported by most astronomy software that provide solver functionality. This makes it a de-facto standard and by supporting the same interface it's easy to test and adopt Watney as well.

The API is "automatically documented" by generating an OpenAPI definition from the sources. Also SwaggerUI is available to help with testing. Examples will be provided here to help with the usage and configuration.

The Interfaces

The API contains two interfaces (or controllers in ASP.NET terms): The Watney "canonical" API (/api/watney/* routes) and the Astrometry.net compatibility API (/api/* routes). Both can be used at the same time. Enabling/disabling the compatibility API can be done via configuration.

The "canonical" Watney API was designed to be the primary API, meaning that its parameters and endpoints were designed with the solver implementation in mind. By design it is also versioned: this is to ensure that backwards compatibility remains. If later on there are changes to the API (parameters changed, fields removed or renamed, etc) a new version will be published. So the original API remains as such under /api/watney/v1 while the new version will be made available under /api/watney/v2 and so forth. This should hopefully bring some stability to the interfaces and give time for any developers to switch to use the new API version.

Watney API interface (/api/watney)

The Watney interface is a pretty minimal set of endpoints to serve the need of simply solving an image and retrieving the results. The v1 contains the following endpoints:

Route	Method	Description
/api/watney/v1/jobs	POST	Posts a new image for the solver to solve. Queues it if the solver is currently solving the max number of concurrent solves.
/api/watney/v1/jobs/{id}	GET	Gets the full currently available job data (input parameters, status, results).
/api/watney/v1/jobs/{id}/status	GET	Gets the status of the job (Queued, Solving, Success, Failure, Error, Timeout, Canceled)
/api/watney/v1/jobs/{id}/wcs	GET	Gets the WCS FITS file from a successful solve
/api/watney/v1/jobs/{id}	DELETE	Cancels the job (removes it from queue if it's waiting, or cancels the running job)

Posting a new job

Endpoint: POST /api/watney/v1/jobs

This is a multipart/form-data type endpoint, i.e. it takes the image as one parameter, and the rest of the parameters by its side as form fields.

The image is simply an file (jpg, png, fits) that is provided as the image parameter.

Then in addition to the image, we have a set of general parameters that are there regardless of whether we're performing a blind or a nearby solve. These are the args.* fields.

The rest of the parameters depend on whether you want to perform a 'blind' or a 'nearby' solve. For 'blind' solve, the fields args.blind.* are to be filled in. For a 'nearby' solve the fields args.nearby.* are to be filled in.

Example of blind solve parameters:

image = m31.jpg
args.maxStars = 300
args.mode = blind
args.sampling = 6
args.blind.minRadius = 0.5
args.blind.maxRadius = 8

And as a CURL command:

curl -X 'POST' \
  'https://localhost:5001/api/watney/v1/jobs' \
  -H 'accept: application/json' \
  -H 'apikey: demoapikey' \
  -H 'Content-Type: multipart/form-data' \
  -F 'args.blind.minRadius=0.5' \
  -F 'args.blind.maxRadius=8' \
  -F 'args.maxStars=300' \
  -F 'args.mode=blind' \
  -F 'args.sampling=6' \
  -F 'image=@m31.jpg;type=image/jpeg'

If the parameters are valid, the successful response will contain the accepted job information:

{
  "id": "tm5lx0174EuriHZUVMZC6A",
  "parameters": {
    "maxStars": 300,
    "sampling": 6,
    "lowerDensityOffset": 1,
    "higherDensityOffset": 1,
    "mode": "blind",
    "nearbyParameters": {
      "ra": null,
      "dec": null,
      "maxFieldRadius": null,
      "minFieldRadius": null,
      "intermediateFieldRadiusSteps": "0",
      "useFitsHeaders": null,
      "searchRadius": 20
    },
    "blindParameters": {
      "minRadius": 0.5,
      "maxRadius": 8,
      "raSearchOrder": null,
      "decSearchOrder": null
    }
  },
  "status": "Solving",
  "imageWidth": 4479,
  "imageHeight": 3375,
  "solution": null,
  "updated": "2022-01-28T20:15:39.0574863+00:00",
  "solveStarted": "2022-01-28T20:15:39.0572873+00:00",
  "originalFilename": "m31.jpg",
  "starsDetected": 7482,
  "starsUsed": null
}