API¶
Introduction¶
This page provides an overview of the OpenAtlas Application Programming Interface (API). The API is RESTlike to provide easy access to the data.
To try out the API first hand, visit https://demo.openatlas.eu/swagger
For developers a complete Swagger documentation is provided.
Quick Start Guide¶
The API can be accessed via the OpenAtlas user interface or through URL GET requests.
1. UI access¶
Each detail view of an entity provide two buttons (JSON and RDF) where the formats, in which the entity should be exported, can be selected. If the buttons are not visible, please change the Show API links at the Display tab in your Profile.
Through the UI, only a single entity can be accessed.
Possible JSON API formats¶
Possible RDF API formats¶
2. URL / GET access¶
The most common way to communicate with the OpenAtlas API is through GET request, either manually from the local browser or with other applications following a specific URL schema:
{domain}/api/{api version}/{endpoint}?{parameter}&{parameter}
- Example URL
- Domain
Location of the OpenAtlas instance from which information should be retrieved; e.g. https://demo-openatlas.eu/ for the demo version.
- API Version
Input without version number leads to the current stable version (https://demo.openatlas.eu/api/entity/5117). If another version of the API is to be used, the version number can be specified (demo.openatlas.eu/api/0.3/entity/5117). A version overview can be found under point Versioning.
- Endpoints
Specific data can be queried by attaching an endpoint (demo.openatlas.eu/api/0.3/entity/5117). The information is provided in a human - and machine-readable form. Further information under Endpoints.
- Required path values
Must be included to create a valid URL. Different endpoints require different values (demo.openatlas.eu/api/0.3/entity/5117. 5117 is an ID as required by the entity endpoint) - all required values are state in { } at the Endpoints definition.
- Parameters
Used to structure additional information for a given URL. They are added to the end of an URL after the “?” symbol (demo.openatlas.eu/api/0.3/entity/5117**?**download=true). All available Parameters can be found under Parameters. For more general information see this article.
Versioning¶
stable |
unstable |
deprecated |
|---|---|---|
The OpenAtlas API follows the notion of sequenced based versioning and reflects the significance: major.minor.fix e.g. 3.11.1. Only the major number is used for the URL path. Minor and fix are used for documentation reasons only with the exception of versions 0.1, 0.2 and 0.3. A stable version of the API will be available at all times. In addition, previous versions will still be usable but tagged as deprecated. A warning will be posted in the roadmap and release notes before these versions will be discontinued. Unstable versions are currently developed, so breaking changes may occur at any time without prior notice.
Endpoints¶
Through different endpoints, data can be retrieved from OpenAtlas. Each version has a own set of endpoints, be sure to use the right one.
The requested information is provided in Linked Places format Linked Places format (LPF). Alternatively, GeoJSON, Linked Open Usable Data or RDFs, derived from the LPF data, can be accessed.
Parameters¶
With parameters the result of the requested endpoint can be manipulated (filtered, searched, sorted, etc.). Each endpoint provide another set of parameters which can be used. So please consult the Endpoints listing for more details.
Parameters are added to the end of an URL after the “?” symbol (e.g. demo.openatlas.eu/api/0.3/entity/5117**?download=true**) and are connected with the “&” sign. For more general information on this topic see this article.
At the moment only the stable version 0.3 of the API can be provided by an detailed parameter list.
Error handling¶
OpenAtlas uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate a successful request while those in the 4xx range signal an error - providing the information was not possible. Codes in the 5xx range indicate a server error. If any issues occur when using the OpenAtlas API, a case-specific error message is provided in JSON format, describing the error in more detail.
Example:
{
"title": "entity does not exist",
"message": "Requested entity does not exist. Try another ID"
"timestamp": "Tue, 19 Jul 2022 13:59:13 GMT",
"status": 404
}
If an invalid endpoint parameter value e.g. ?sort=kfs instead of ?sort=desc is entered, Flask catches this via its own Flask-RESTful extension. An error message is provided by its own error handler error handler
Authentication guide¶
No authentication is needed to use the OpenAtlas API.