Note: due to deficiencies in the Swagger codegen tools, the auto-generated API docs are missing descriptions of some parameters, and some optional parameters are incorrectly marked required. Where there are disagreements, the documentation in this wiki should be considered authoritative. The position of the parameters in the API docs (path argument, query argument, form data, multipart part) is correct.

Many of the APIs accept and/or return either key/value maps, or objects. In almost all cases these are represented as Json; in some cases it's form-data or a multipart request or response. Endpoints that may return more than one result return a (possibly empty) Json array.

Some of the API endpoints return collections of objects. In many cases the size of the collection is effectively unbounded, so the result may be broken up into a series of HTTP responses, each comprising a json array containing one page of the result, and a PageInfo object which contains, among other things, a continuationToken. The continuationToken may be used in a subsequent request to obtain the next page of data (along with the next continuationToken). PageInfo also contains nextLink, a complete URL which may be used to GET the next page.

In most cases the client may specify the maximum number of elements on a page, but the services also impose an upper bound on that maximum, so production clients must be prepased to receive partial results and request more.

Our Java client libraries (RestLockssRepository, RestConfigClient, etc.) hide these paged results behind Java Iterators and Iterables which implement the necessary paging logic, so clients of these libraries need not be aware of the paging. Other clients, including those using libraries auto-generated from the Swagger API descriptions, must implement the paging logic themselves.

All the services support GET /apiStatus, which returns an ApiStatus object containing at least the API version and a ready boolean. Clients should not make other calls to the service unitl ready is true.