API basics
What is a Web API?¶
API stands for Application Programming Interface. It allows two software applications to communicate with one another to exchange data. A Web API is a specific type of API in which the communication takes place using HTTP requests.
How does Nexus Web API work?¶
Nexus provides a Web API for obtaining data from the platform. For consuming data Nexus offers OGC-compliant services: WFS, WMS and WCS.
The Nexus Web API can be reached at https://nexus.stellaspark.com/api/v1/.
This URL is called the API root. You need a Nexus Web API token to use it.
Getting your Nexus Web API token¶
To use the Nexus Web API, you need a Nexus user account that has been assigned the Data Consumer or Data Supplier role. Email StellaSpark in case this role is not yet assigned to your account. Once this role is assigned to you, you'll receive an email containing a Nexus Web API token. With this token you can make API calls. Keep the token to yourself and never share it publicly.
Requests and responses¶
You can communicate with Nexus API by performing requests. A so-called GET request is used to retrieve data from Nexus, and a POST request to send instructions to Nexus. For both GET and POST requests, Nexus returns a response. Both the request and the response contain two parts: headers and a body. Headers describe meta-information, and the body contains the actual data to be transmitted.
Return codes¶
For each request, you will receive a return code with the response. This HTTP return code indicates whether the request was successful or not.
| Code | Meaning | Reason |
|---|---|---|
| 200 | Success | Request was successfully processed |
| 400 | Bad request | You may not be authorized or have mistyped part of the request. |
Request parameters¶
When retrieving data, you need to 'tell' the API exactly which data you want and how you want it.
This is done by adding parameters after the API service name. Always add a ? at the end of the service name, and
then specify parameters as key:value pairs. You can combine parameters in a request by using &.
Example
A full API request is the combined root, service name and any additional parameters:
API root/service/?parameter=value¶meter=value
In full form (for example with WFS as service):
https://nexus.stellaspark.com/api/v1/wfs/?token={web_api_token}&world=sandbox&request=getcapabilities
Request encoding¶
All parameter values should be encoded to HTTP-safe characters. For example, whitespace is encoded to '+' and a 'greater than' sign (>) to '%3E'. When sending a request to Nexus, be sure to properly encode all parameter values. Some client tools will already do this on-the-fly, others provide encoding and decoding methods.
Tools¶
You can experiment with GET-requests simply by entering the full API URL into the address bar of your web browser. For POST-requests and requests that contain custom headers, it is recommended to use cURL. This command line tool is available on any Windows and Linux system and is started by simply opening a command prompt or terminal and entering:
curl