API status codes

HTTP status codes will be used to report status of the calls.

As a basis, the clients need to be able to understand that:

  • 2xx means OK
    • Hence the API clients should treat all status codes in the 2XX series as success - the client implementation must also be robust enough to handle changes between codes in the 2XX series.
  • 3xx means redirect that needs to be followed
  • 4xx means that something is wrong with the client´s behavior and that something hence needs to be reformulated or alternative resources must be used to perform the task.
    • Note however that 404 Not found in some cases is expected behavior, and hence does not indicate anything wrong with the client behavior.
  • 5xx which means there is a (temporary) error on the server side that needs to be handled by a retry.

Redirects

  • The client systems should be able to handle redirects (HTTP Status Code 301 or 307) and not found (404)
  • When response is 404 on a stored resource URL, the client systems should try to find the resource by going through the top-level lookup of users and follow links, or select a specific URI template.
  • When response is 301 to a GET on a stored resource URL, the client system should update the stored URL to the one contained in the response, and GET on the new URL.
  • When response is 307 to a GET on a stored resource URL, the client system should leave the stored URL as is, but GET on the URL contained in the location header in the response.
  • There will be no redirect on POSTs. When POSTing a resource with a URL not existing, 404 NOT FOUND will be returned.

Redirect example

When the business unit TNN gets rights for a user, the following URL may be used when GETting: https://apihost/user/12345/rights. The response may then be a temporary redirect (307) to https://apihost/user/12345/rights?grantorid=TNN_FIXED&grantorid=TNN_MOBILE.

If URLs are changed, probably a 301 (Moved Permanently) will be returned with a Location to the new URL, this will then indicatethat the client should update the bookmark (stored URL). In other cases, e.g. when retrieving rights, a GET on users/USERID/rights with API user FOO potentially will give a 307 (Temporary Redirect) to users/USERID/rights?grantorid=FOO_GRANTOR. The client should then automatically follow redirect, but not necessarily update bookmark (stored URL).

There could be some cases were it is not possible to give a 3xx, in those cases a 404 is given. It is then up to the client to have an alternative strategy to perform the task.

Suggestion for how to handle 5xx errors

If the client gets 500 or 503 it should wait some seconds and then resend the request with an increasing time interval between each retry (backoff/retry). For instance in a sequence like this: 1-1-2-3-5-8-13-21 etc. 10 retries is maybe enough? - If this is difficult or impossible to implement the client must not implement this, but we then risk that 503 overload lasts longer. If there is some standard solution for backoff/retry in the integration software please inform Telenor Digital about this solution.

Suggestion for how to handle no response from the API

If the client gets no response from the API (time out errors) on GET, PUT and DELETE requests, retries can be performed without problem.

If the client gets no response from the API on a POST request, retries can lead to creating the object twice. Retry is NOT a preferred solution for handling time out errors of POST requests.

There are two options for handling time out errors of POST requests:

  1. Automatic procedure
    • Perform a get request for the object type
    • Assess if the specific object you wanted to create is there
      • If yes: store the ID
      • If no: POST again
  2. Manual followup of all POST request that get no response from the API

Logging and monitoring of 4xx and 5xx errors

The client should log all 4xx (except 404 Not found) and 5xx errors that occur. Operations / Application Management should monitor this log.

HTTP status codes

This section lists some typical status codes returned for the different HTTP methods. Note that some of the status codes will be returned by GBE (typically those described below) - and some might be general HTTP codes that are not explicitly returned by GBE.

200 OK
The request has succeeded. The information returned with the response is dependent on the method used in the request.
201 Created
The request has been fulfilled and resulted in a new resource being created. The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field.
204 No Content
The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.
301 Moved Permanently
The requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs. The new permanent URI SHOULD be given by the Location field in the response.
303 See Other
The response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource. This method exists primarily to allow the output of a POST-activated script to redirect the user agent to a selected resource. The new URI is not a substitute reference for the originally requested resource.
307 Temporary Redirect
The requested resource resides temporarily under a different URI. Since the redirection MAY be altered on occasion, the client SHOULD continue to use the Request-URI for future requests. The temporary URI SHOULD be given by the Location field in the response.
400 Bad Request
The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
401 Unauthorized
The request requires user authentication. The response MUST include a WWW-Authenticate header field containing a challenge applicable to the requested resource. The client MAY repeat the request with a suitable Authorization header field. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials.
403 Forbidden
The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.
404 Not Found
The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.
409 Conflict
The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.
500 Internal Server Error
The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable
The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response.

The following table illustrates which status codes are typically relevant for which HTTP method.

Code GET PUT POST DELETE
200 Ok x x
201 Created x
204 No Content x
301 Moved Permanently x
303 See Other x
307 Temporary Redirect x
400 Bad Request x x x
401 Unauthorized x x x x
403 Forbidden x x x x
404 Not Found x x
409 Conflict x x
500 Internal Server Error x x x x
503 Service Unavailable x x x x

Resources

The definition of HTTP status codes are mainly found in RFC 7231 - HTTP/1.1 Semantics and Content and RFC 7232 - HTTP/1.1 Conditional Requests.