[% IF uri -%] [% END -%] [% title %] [% IF uri -%] [% END -%]

This documentation describes the Sipwise NGCP HTTP API, which is used to control the NGCP platform via 3rd party applications. It is also a machine-readable service document and serves as entry point for API clients.

The Sipwise NGCP HTTP API strictly follows the REST principle and uses the JSON Hypertext Application Language (JSON-HAL) to express resources and their relations. This means, compared to typical plain JSON APIs, that relations between resources are defined as hyperlinks within the JSON objects, so a client can and should navigate between related objects without hard-coding any URIs.

Brief Overview of JSON-HAL HAL is a generic media type with which Web APIs can be developed and exposed as series of links. Clients of these APIs can select links by their link relation type and traverse them in order to progress through the application. A HAL document uses the format described in RFC4627 - The application/json Media Type for JavaScript Object Notation (JSON) and has the media type application/hal+json. An example request to fetch a customercontacts item with id 1 via the API looks like this:


   GET /api/customercontacts/1 HTTP/1.1
   Accept: application/hal+json

The corresponding response is as follows:


   HTTP/1.1 200 OK
   Content-Type: application/hal+json

   {
     "_links": {
       "self": { "href": "/api/customercontacts/1" },
       "ngcp:reseller": { "href": "/api/resellers/5" },
     },
     "firstname": "John",
     "lastname": "Doe",
     "email": "john.doe@example.org"
   }

Here, we have a HAL document representing a contact resource with the URI /api/customercontacts/1. It has a link to a reseller it belongs to, and its own state in the form of firstname, lastname and email properties. To fetch the reseller of this contact, an API client only has to follow the link provided in _links.reseller.href. A simple code example might look like this:


  $ua = LWP::UserAgent->new;

  # fetch the contact (URI hardcoded for simplicity only!)
  $contact = from_json($ua->get('https://example.org/api/customercontacts/1'));

  # follow the reseller link to fetch the reseller of this contact
  $reseller = from_json($ua->get($contact->{'_links'}->{'ngcp:reseller'}->{'href'});

API Versioning Due to the JSON-HAL structure, all related resources are hyperlinked, which implies that no strict API versioning is required. If URIs change between NGCP versions, the hyperlinks in the JSON-HAL documents are updated accordingly. As a consequence, this means that a client implemented against the API should not hardcode URIs, rather than using the hyperlinks provided in the resources. Query Parameters Some collections define query parameters to filter the output. Typical use cases are limiting collections to a specific reseller or a specific customer. Query parameters are appended to the URL like in the following example:


curl -X GET 'https://example.org:1443/api/somecollection/?param_one=1&param2=something'

Some query parameters allow wildcard/pattern matching, which is expressed by a '*' like this:


curl -X GET 'https://example.org:1443/api/somecollection/?param=*something*'

Note: this examples do not yet contain authentication and will therefore not work on a standard installation. To read more about that go to the Chapter Authentication. HTTP Response Codes The REST API returns an HTTP response code with the following classes:

1xx: Provisioninal Response - the client is asked to proceed with the request.
2xx: Successful Response - the request has successfully been received and processed.
3xx: Redirection Response - the client is asked to contact a different location.
4xx: Client Error - the client has provided incorrect information in either the credentials, the location or the data.
5xx: Server Error - the server failed to process the request due to an internal error.

1xx Provisional Responses The server sends the following provisional responses, and the user agent on the client is expected to handle it transparently without any special handling in the code using the API:

100 Continue: The client should continue with its request. This interim response is used to inform the client that the initial part of the request has been received and has not yet been rejected by the server. The client should continue by sending the remainder of the request or, if the request has already been completed, ignore this response.

2xx Successful Responses The server sends the following successful responses:

200 OK: The 200 code is sent in response code to a successful GET request on a collection or item, or if a PUT or PATCH request with a Prefer: return=representation header is processed successfully. The body contains the result of the operation.
201 Created: The 201 code is sent in response to a successful POST request creating an item within a collection.
204 No Content: The 204 code is sent in response to a successful PUT or PATCH request with no Prefer header or with Prefer: return=minimal and to a successful DELETE request.

3xx Redirection Responses The server redirects the clients using the following return codes:

301 Moved Permanently: The 301 code is sent in response to a request towards a collection without a trailing slash, e.g. http://example.org:1443/api/something is redirected to http://example.org:1443/api/something/.

4xx Client Error The server rejects a client request with the following response codes:

400 Bad Request: The 400 code is sent in response to a request not validating basic syntactical and semantical rules. These rules include a missing body in a POST, PUT or PATCH request, an invalid body in a PATCH request, invalid operations in a PATCH request, or a malformed body based on the expected content type.
401 Unauthorized: The 401 code is sent in response to a request lacking an Authorization header if no SSL authentication is performed, or an Authorization header with invalid credentials.
403 Forbidden: The 403 code is sent in response to a request trying to access resources which require different privileges (typically a reseller accessing resources of other resellers or of the system), or if you try to create more subscribers than allowed within a customer, or if you try to authenticate with an SSL client certificate with an invalid serial number.
404 Not Found: The 404 code is sent in response to a request trying to access an invalid URL on the system, or if it is trying to perform an operation on an item which does not exist or the user has no access to (e.g. a reseller trying to access items of a different reseller).
415 Unsupported Media Type: The 415 code is sent in response to a PUT, POST or PATCH request which doesn't provide an acceptable Content-Type header. Content types are usually application/json or application/json-patch+json for POST/PUT and PATCH, respectively. However, some resources require different content types like audio/x-wav.
422 Unprocessible Entity: The 422 code is sent in response to a syntactically valid request, which fails to meet semantical conditions, like missing or invalid fields in a JSON structure. The body of the response provides more information about the exact condition that failed.
423 Locked: The 423 code is sent if you try to delete an item which is still in use. This is typically the case when trying to delete system or customer contacts which are still bound to a contract.

5xx Server Error The server sends the following error codes in case of internal issues:

500 Server Internal Error: The 500 code is sent in response to a request which caused an unrecoverable error while processing the request. This is usually caused by database errors when modifying data, and they should never happen. If a 500 is encountered, please open a support ticket with Sipwise, providing the data you passed to the server (URL, headers, body), and the error messages provided in /var/log/ngcp/panel*.log of the server.

[% # vim: set tabstop=4 syntax=html expandtab: -%]