Overview
Documentation on the REST APIs.
General Principles
The REST APIs were designed with some general principles in mind
- Each REST method takes an authToken that can be obtained from the security service
- Each REST method validates the token and then authorizes the user's action based on role.
- Some methods consider "application role"
- some methods consider "project specific role"
- Error handling is consistently managed at the REST layer
- Print a stack trace
- Send an email to an administrator list (unless its a known condition that does not require notification, such as a failure to authenticate)
- Return an HTTPS 401 or 500 error with an appropriate error message
- Each REST method opens one or more internal JPA services, performs their operations, and then closes the resources at the end.
- Each REST method is designed to provide information to clients at a level that generally does not require chained callbacks. In some cases model objects have "transient" fields that are not persisted but are populated by the REST layer to ensure the client has enough information from a single call to avoid other calls.
- Generally getter methods use GET
- Generally write methods use PUT, POST, or DELETE.
- Generally finder methods return "search result lists" and support the use of a "pfs parameter" (paging/filtering/sorting).
- Lists are wrapped classes designed to persist nicely into JSON for a Javascript client (e.g. see ConceptListJpa).
- Application paging is done on the server side. The javascript requests a page of content that includes the total count (so the number of pages can be easily computed). A request for the next page always makes a server callback.
Specific API Documentation
The best documentation on the REST services are in the Swagger UI for the services and in the code itself. Reiterating that information here would likely lead to inaccuracies. Please consult the API documentation here
References/Links
- n/a