How to use Drifty
Vocabulary
The Drifty documentation uses a number of terms with a specific meaning, so its best to first learn the meaning of those. Here they come:
- Model: The OpenDrift library can run trajectory simulations for a number of different types of objects and substances. Each category of object/substance has its own algorithm, with specific options. These are called models, e.g leeway, oildrift, shipdrift.
- Seed: When specifying a simulation, the most important part is to give a clear definition of the object of which you want to simulate the drift trajectory. This includes information about the object itself and the geographical placement of the object(s). This part of the simulation specification we call seed. Please note that while opendrift support specifying multiple, separate seeds for a simulation, drifty supports only one seed specification pr. simulation run.
Creating a client
A client is meant to interact with Drifty in an asynchronous manner. That is, the client will post a simulation, receive an immediate response, but will need to regularly poll the api, waiting for the simulation to complete. Drifty is based on an async request-reply pattern, but please note that details in Drifty will differ from any other implementation of the same pattern.
The Drifty API has a machine-readable specification, written in OpenAPI version 3.. The human readable api reference documentation is auto-generated based on that OpenAPI specification.
Each OpenDrift model has its own resource. Each model resource has its own api specification, as the various of options for specificying a simulation run varies between each model.
Currently we have no existing client library support. So you have to write your own client code, to integrate with Drifty. This you can do either by generating code from the OpenAPI specification, or by using the api documentation as reference while writing the code manually.
Authentication
Drifty uses basic authentication, and each user of Drifty will get their own username and password when we set up their account.
Versioning
Drifty API has a major version number for each model resource. The version number is treated as the major version number in semantic versioning. Smaller, backwards compatible changes will be done continuously. Particularly, we will add new options to a model resource by updating the OpenAPI specification.
For all significant changes, we will send out a description of the change on the mailinglist. We will also update the changelog.
Error handling
We use regular 4xx and 5xx http status codes, as close as possible to the HTTP specification. Some errors will have a message of what went wrong in it. Some errors will respond with json. Do not encode those json error responses, as they might change without proper versioning as described above.