Download PDF

Methodology.

We have a growing number of APIs available to clients through the SamKnows One platform.

All our APIs are HTTP APIs, designed to be easy to use and integrate into internal tooling such as customer care systems, networking provisioning management, automation tools or internal monitoring.

Format

All of our APIs expect requests to be in JSON and responses, unless otherwise stated (for example CSVs), are in JSON also.

RESTish

Our APIs follow a non-strict REST approach, in that we make use of HTTP verbs and HTTP status codes, but APIs are structured for usability as opposed to being strictly RESTful.

Common HTTP verbs:

  • GET - Fetching information or data but makes no changes to data (other than audit logging)
  • PUT - Updating an already existing object
  • POST - Creation of an object or, in some instances such as analytics, 'creating an analytics request'
  • DELETE - Deletion of an object, note this does not necessarily mean deleted from our databases, but can often just mean hidden/disabled

Common HTTP status codes:

  • 200 OK - Standard success message
  • 201 Created - A new object has been created successfully
  • 202 Accepted - Your request has been added to a queue and will be processed in the background
  • 401 Unauthorized - No authentication token was detected
  • 403 Forbidden - You were authenticated but don't have permission to access the resource
  • 403 Forbidden - You were authenticated but don't have permission to access the resource
  • 404 Not Found - The resource/object requested could not be found / does not exist
  • 422 Unprocessable Entity - Validation error or we're unable to complete the request (for example because you've hit your CPE usage limit)
  • 500 Internal Server Error - Something went wrong on SamKnows' side, this will trigger internal monitoring tools.

Authentication

Authentication to our APIs is always token based. You can retrieve a token from within SamKnows One, and also regenerate your token. Note that a token is for an entire organisation so regenerating it may affect other users also. It is passed in an Authorization header in the format Authorization: Bearer {token}.

Communication

All communication with APIs should be over HTTP with TLS 1.2.

Error handling

If an internal error occurs in SamKnows systems then development teams will be notified (see Platform Monitoring), however if it continues to persist, please do contact your account manager.

An error would give a response as follows

+ Response 500 (application/json)

          + Body

                      {
                        "code": "UNKNOWN_ERROR",
                        "message": "An unexpected error has occurred. This has been reported to our engineering teams, please try again shortly.",
                      }

Development

Developer documentation is available on the relevant pages in this section of SamKnows One. URLs for production and development purposes will be shown within SamKnows One as a logged-in user with appropriate access.

Performance and capacity

We actively manage capacity planning to ensure that the API can handle as many simultaneous connections/sessions as required by our clients.

Logging

All API hits are logged internally by SamKnows for auditing, error monitoring and analytics purposes.