Architecture

In short, we have used the microservices architecture approach. Each project/application/service mentioned is its own set of multi-threaded processes and is distributed across multiple UNIX-based servers. We refer to these individual projects/applications/services as endpoints.

The endpoints use lightweight HTTP REST with JSON to communicate with each other. High availability proxies ensure the API interfaces, internally and externally, are always available.

All functionality seen on the web interface is accessed via our API(s). Therefore you can expect no limitations using the API interfaces.

There are several services/applications provided by our platform:

• Identity (IAM) - Identity and access management.

• Telemetry - Telemetry for all the different services.

• Subscriber - Subscriber Management platform.

Each application has its own User Interface views and API resources.

Please refer to Service Endpoints for a list.

Versioning

We are continuously improving the platform and adding and removing unused API(s) and parameters returned. In the resource URL, the prefix will be the version for the specific resource like /v1... /v2... When a specific API becomes obsolete or ready for deprecation we will advise our customers that are consuming the specific resource in advance.

Error Response

Errors are a crucial part of the developer experience when using an API. As developers learn the API, they inevitably run into errors. The quality and consistency of the error messages returned to them will play a large part in how quickly they can learn the API, how they can be more effective with the API, and how much they enjoy using the API.

The response will follow a standard reply if an error occurs due to a bad request or internal backend error.

{
    "error": {
        "title": "Short Error Title",
        "description": "Descriptive message",
        "request_id": "Unique API Request ID"
    }
}

The request_id can be used by the NebularStack team to trace detailed backend system logs relating to the API request. It is recommended that if the error is unexpected, this ID is provided to our team for further analysis.

Please note if, for whatever reason, our API service is down and your request reaches our load balancers, the error will be HTTP Status Code >= 500 with the content type of not JSON. In this scenario, you will not get a standardised error message.

HTTP Status Codes

• Payment Required / Out of Credits: The request is blocked and returns status code 402.

• Authentication Required HTTP Status Code 401.

• Access Denied HTTP Status Code 403. Insufficient privileges and is blocked by policy.

• Synchronous resource creation.

  • Response Status Code: 200 OK

    • Returns Body with Object of Created Resource.

  • Response Status Code: 201 Created

    • Returns Location header with the URI of the created resource.

• Asynchronous resource creation.

  • Response Status Code: 202 Accepted

  • Optional location header is set to permitted callback/webhook URI.

• Synchronous resource deletion: 204 No Content

• The return code should be 200 OK for all other successful requests.

• The return code should be 400 Bad Request for badly formatted requests and invalid requests.

• Reference not found to resource in the request URI returns HTTP 404 Not Found.

• If a request contains a reference to a nonexistent resource in the body (not URI/URL), the code should be 400 Bad Request.

• If a request's body contains an unexpected attribute, the server should return a 400 Bad Request response.

• Conflicts such as duplicate creation of unique accounts should return 409 Conflict.

• Service Unavailable HTTP Status Codes 500, 502, 503, and 504 are due to maintenance and connectivity and should be temporary.

HTTP Methods