Akkroo

API Principles

This page contains information about features common to the whole API.

Collections and Models

The Akkroo API uses the concept of collections and models for most endpoints. A collection is a set of models which can be searched and added to. A model is an individual item which can be manipulated. For example, a collection of events would be a list of several events, an event model is just one event. Models may also be referred to as “resources”, particularly when specifying a resource range.

Accessing collections and models follows the same URI pattern across the API. Collections are accessed by using the name of the collection, e.g.:

GET /api/events

Models inside that collection are accessed by their ID:

GET /api/events/2311

Some models have collections belonging to them, for example an event will have a collection of registrations. This is represented in the URI as:

GET /api/events/2311/registrations

To access a registration model:

GET /api/events/2311/registrations/52018d84fd1dc9f15eb6701e

Collections always return an array of model objects. Each model object has an "id" attribute. The other fields in each type of model are specified in the relevant page in Endpoints

Specifying a resource range

When fetching a collection with many items, you may want to restrict the maximum items returned in one request, or only fetch a subset of the items. To specify a range of resources when fetching from a collection, use the Range header:

GET /api/events HTTP/1.1
Range: resources=0-10

This will return the first 10 models, or all the models if there are less than 10. The response will have a 206 Partial Content status code if this does not include all resources. The range of resources in the response is indicated in the Content-Range header, in the format Content-Range: resources <from>-<to>/<total>:

HTTP 206 Partial Content
Content-Range: resources 0-10/15

If you just need to retrieve a count of the number of models in a collection, use HEAD or request a range of 0-0 and parse the Content-Range header.

If you do not specify any Content-Range the default value will be 0-20.

As of version 1.1.5 the limit is 1000 items per request.

This means you will have to implement pagination whenever you want to fetch more than 1000 items.

Query Parameters

Query parameters can be used when performing read requests to alter or restrict the set of data returned. Some query parameters are available on all endpoints, some parameters are endpoint-specific.

For example, the fields parameter is available on all endpoints to restrict the fields returned by the endpoint:

GET /api/events?fields=name,type

Would return only the name and type attributes of events:

[
	{
		"name":"Lancaster University Freshers Fair",
		"type":1
	},
	{
		"name":"Manchester University Careers Fair",
		"type":1
	}
]

Common query parameters

These parameters are available on all endpoints

Parameter Values Default Description
fields Comma-seperated list of endpoint fields. Invalid fields will be ignored. An empty list will return an invalidQueryParameterValue error No value (i.e. all fields) Restricts the attributes returned on each model

HTTP Methods

The Akkroo API utilises HEAD, GET, OPTIONS, POST, PUT, and DELETE from HTTP/1.1, and PATCH from RFC 5789.

OPTIONS

OPTIONS allows the client to determine what methods are allowed on a specific endpoint.

OPTIONS /api/events

Response:

HTTP 204 No Content
Allow: OPTIONS, HEAD, GET, POST

HEAD requests are the same as GET requests, but do not include the request body. The API will not actually pull the data from the database for a HEAD request, so these are generally quicker to process than GET requests. HEAD requests are useful for determining the resource count.

GET

GET requests are used to fetch the data from a collection or model. If the requested endpoint is a collection, an array of model objects will be returned in the body; if it is a model a single object will be returned.

The response also contains a Last-Modified following Akkroo Date and Timestamp Formats. The request can contain a If-Modified-Since timestamp (again, RFC 1123 format) specifying the last modified timestamp of it’s locally cached data. This can be used on models and collections. If the server has new data, it will respond as usual. If it does not, it will respond with a 304 Not Modified status and an empty response body. Known issue: if specifying an If-Modified-Since header on a collection and also specifying additional filter parameters or requesting a limited range of data, the API will check the timestamp against all data in the collection instead of the subset requested.

POST

POST requests are usually performed on a collection endpoint to create a new model. The request body should contain all data required to create the new model. If successful, the API will respond with a 201 Created status code and an object containing the id in the request body:

POST /api/events HTTP/1.1

{...}

Response:

HTTP 201 Created

{"id":4524}

PUT

PUT is used to replace an existing model with new data. It can only be used on model endpoints. For both PUT and PATCH, the client must specify an If-Unmodified-Since header (HTTP-date format e.g. Wed, 15 May 2013 09:18:19 GMT) to indicate to the server that the client is making modifications based on an up-to-date local cache of the resource. If the client specifies an outdated timestamp, the API will respond with 412 Precondition Failed.

PATCH

PATCH is used to update a model by changing only the specified attributes. For example, to change the name of the event, the request body would be

PATCH /api/events/4524 HTTP/1.1

{
	"name":"New event name"
}

Otherwise, PATCH is identical to PUT in behaviour.

DELETE

DELETE is used to delete a single model, or all items from a collection (if allowed).

DELETE /api/events/4524

Response:

HTTP 204 No Content

HTTP Status Codes

Status codes are used as defined in HTTP/1.1. Below are descriptions of the status codes used in the API.

Code Status Description
200 OK The request was completed successfully
201 Created The resource was created successfully. Look in the body for the resource ID.
204 No Content The request was successful, but there was no content in the response. Used for PUT, PATCH and DELETE.
206 Partial Content Only a subset of all available data was returned, either by request (Range header) or because the API endpoint is limited to a maximum number of resources per request. Check the Content-Range value to see what the subset was.
304 Not Modified The resource has not been modified since the If-Modified-Since timestamp. The response body is empty.
400 Bad Request Data supplied in the request is invalid. See the response body for further details of the error
401 Unauthorized The client has not provided authentication to access the endpoint, or the authorisation provided is invalid
403 Forbidden The authorisation provided has expired, or the request requires higher privileges than provided by the access token
404 Not Found The resource specified could not be found
405 Method Not Allowed The HTTP method used is not allowed on this endpoint
406 Not Acceptable An Accept header was not provided in the request, or none of the specified acceptable response versions are provided by the API
409 Conflict The data supplied in the request conflicted with data already on the server. This will usually be because of a unique field, such as the values.email.value field on the Registrations endpoint.
410 Gone The resource did exist at some point, but it's gone now.
412 Precondition Failed The resource on the server has been modified since the timestamp supplied in the request's If-Unmodified-Since header. Can occur when trying to update a resource with PUT or PATCH.
416 Requested Range Not Satisfiable The range requested in the Range header was invalid, i.e. the range start was greater than the number of resources
500 Internal Server Error Hopefully you will never see this! This means something went wrong on our end. We should spot this in the logs, but please drop us an email detailing the exact request (headers and body) that caused this to occur.
501 Not Implemented The HTTP method used is not implemented on the Akkroo API.

Date and Timestamp Formats

Akkroo formats dates and timestamps according to RFC 1123 (HTTP-date).

Encryption

All Akkroo domains are encrypted with SSL 3.0 or TLS 1.0 to 1.2. Unsecured connections are not allowed, and are redirected to HTTPS (port 443). We also send a HTTP Strict Transport Security header to help protect against Man-In-The-Middle attacks.

Akkroo has an A rating on Qualys SSL Labs test.