Rest API documentation

Owned by bcarlsen (Unlicensed)
Jun 01, 2015

Overview

Documents the REST APIs.

This is a placeholder page with basic information and will be developed to fully document this aspect of the system.

Details

The REST services are built as a layer on top of the internal service APIs. This way, the REST layer can focus on the interactions with the client, security, and lazy initialization (or depth-of-graph resolution) without needing to also focus on core functionality.  Every REST service call (except the security service authentication method) takes an authorization token that is validated in two ways. First, the system verifies the authorization and timestamp of the token against a service-layer stored token (for example, a token retrieved from UTS security services), then verifies that the application grants the user in question access to the REST call. Any authentication or authorization failure results in a HTTP 401 error.

The application supports two failure modes: expected errors and unexpected errors. An example of an expected error is when a user attempting to access a REST service with an invalid authorization token. This is a known condition that is planned for and explicitly handled. In this event a user friendly error message is passed back with an HTTP 401 or 500 status code and any application can expect to simply display this message to the user with no further action needed. In the event of an unexpected condition, a user friendly error message of the style “Unexpected exception …” will be passed. For all unexpected failures, the administrators of the system will be sent an email notification containing the stack trace as well as parameter and other information.

The naming convention for REST services URLs is based around the “type” of service with the next section of this document detailing the service types and the functionality available. Typically, simple parameters are passed as URL path parameters while more complicated objects like the paging/sorting/filtering parameter being passed as POST data. For “add” and “update” calls, JSON or XML data structures representing the underlying model objects are passed as POST data.

There is a well-documented Swagger API for these services that provides sample values for individual parameters that when used in the demonstration system produce expected results.

General Design

  • get/find use GET method
  • find methods take paging/filtering/sorting/[criteria] parameters.
  • get methods for ids that do not exist return null.
  • add uses PUT
  • update uses POST
  • delete uses DELETE
  • actions use POST or GET.