Developer Guide
This guide is intended for application developers using the Satcom Global APIs. The guide is delivered in sections:
A general introduction that discusses the subscription process, authorization, and API versioning (this section).
Specific sections for each API. These are intended to give an overview of the API features, the expected order of calls and any other business rules associated with the API.
The full details for each API method are listed in the APIs section. This section also allows you to make calls to the API methods from within the developer portal.
We do our best to ensure these developer guides are up to date, but the definitive API definitions are always those shown for the API methods in the APIs section.
Introduction
Our APIs are organized around Open API (REST). They use predictable resource-oriented URIs, accept JSON encoded request bodies, return JSON encoded response bodies, and use standard HTTP verbs and response codes. API users must register with our developer portal and subscribe to obtain API keys. The API keys are then used to authenticate with the API endpoints and control authorization of access to resources.
Registration
The first step to using the Satcom Global APIs is to register with the developer portal at:
https://sg-apim-rn.developer.azure-api.net/
You must supply and confirm your email address and a password for sign-in to the developer portal. Once you have registered, you can subscribe to individual API products and use your subscription keys to authorise with the API endpoints, as described in the following section.
Subscription
Our APIs use the concepts of Products, APIs and Subscriptions to control access to the API features. A Product is a collection of APIs; you subscribe to a Product to gain access to all the APIs in that Product. For example, to use the Aura Now API you will need an active subscription key specific to our Aura Now product. Go to the "Products" section in the main menu, click on the "Aura Now" product, enter a name for your subscription (e.g. your application or company name), and click the "Subscribe" button. Your subscription request will be held by our system until it is "activated" by our developer administration team. When your subscription has been activated, you will receive an email notification and can access your subscription keys in the "Profile" section. There are two keys with each subscription to allow for key-rotation without service interruption. Your subscription keys are mapped to your account details in our backend systems. This mapping is configured by our developer administration team before your subscription is activated. Please treat your API keys as you would treat sensitive login/password data, they give the same level of access to your data as the user account that they are linked to.
Authorisation
Authorisation for the API requires you to supply your subscription key in the HTTP request header:
Ocp-Apim-Subscription-Key: your-subscription-keyYour subscription key is specific to an individual product and its associated APIs. Ensure you use the correct subscription key for the API you are accessing. Your subscription key is available in your account Profile section.
API Versions
Our APIs are versioned with a version identifier in the path of the request URI. For example version one of the API is held under the path /api/v1/
A new version of the API will be released if it includes breaking changes to the current API version. Breaking changes include changes to request parameter names or property names, but would not normally include the addition of properties to response objects, or the addition of extra features to an existing request.
Breaking changes include:
a change in the format of the response data for one or more calls
a change in the request or response type (i.e. changing an integer to a float)
removing any part of the API
Non-breaking changes include:
the addition of attributes to a resource
the addition of resources
Example of a breaking change:
POST /api/v1/transactions
{
"id": "16833741-33a0-437c-9c82-7f6",
"from": "20-01-2020",
"to": "20-02-2020",
"currency": "USD",
"amount": 314.55
}
The "from" and "to" properties have changed to "from-date" and "to-date"
POST /api/v2/transactions
{
"id": "16833741-33a0-437c-9c82-7f6",
"from-date": "20-01-2020",
"to-date": "20-02-2020",
"currency": "USD",
"amount": 314.55
}
HTTP Response Codes
This section details the HTTP response codes used by the API to indicate the result of requests. We have deliberately limited the number of possible response codes to make it easier to handle error responses in the client.
200 OK
This is the default response if the method call was successful. The response body will contain data relating to the request.
400 Bad Request
This indicates that there is a problem with the parameters of the request as supplied. This is used for input validation errors. The request body may include text describing the problem. An example would be requesting the latest pre-paid balance on a post-paid SIM; this is not a valid request and will return a 400 Bad Request response.
The API methods may also return 400 Bad Request for items in the request body of POST, PUT and PATCH requests. For example if setting the user's employer with a update request:
PUT /api/users/215
{ "id": 215, "name": "Example User", "employer_id": 15 }In the above example, if no employer with Id of 15 is found, a 400 Bad Request error is returned. The response body may include a message such as "employer id not found".
401 Unauthorized
This indicates that the Subscription Key HTTP header (or other authorization header) is missing, or that the Subscription Key supplied is not valid; it does not match any subscription keys held by the system.
403 Forbidden
This indicates that the authenticated user is not allowed to take the requested action. An example of this would be trying to update a resource when you do not have "update" permissions on the item. Another example would be trying to access an item that you do not have read permissions for.
404 Not Found
This indicates the item requested has not been found in the system. An example request might be:
GET /api/users/127This would normally retrieve details of the user with Id 127. If user 127 does not exist, a 404 Not Found is returned.
429 Too Many Requests
This error indicates that the client has exceeded the rate limit for their subscription. For example a client may be restricted to 10 calls in any interval of 10 seconds; if the client sends an 11th request within a 10 second interval the response to the final request will be error 429.
500 Internal Server Error
This error indicates that an unexpected problem was encountered on the server side whilst processing the request. Examples of this might be networking or database access problems.