Principles

The API is designed to provide consistent and predictable interfaces across resources

Resources

API resource interfaces should follow a consistent naming convention that describes what request the resource is for. For a resource called Activity it might have the following interfaces:

• GetAcitivtyData - Data returned from fetching the resource (e.g. GET request)

• GetActivityQuery - Query parameters that can be sent when fetching a resource

• UpdateActivityData - Data sent to the API when updating a resource (e.g. PUT request)

• CreateActivityData - Data sent to the API when creating a resource (e.g. POST request)

Pagination

For requests that can return lots of results the API uses a standard pagination interface that specifies how to query, sort and return paginated data.​Write a caption​

Rules

Pagination can have a rules query parameter which filters the results from the API. Each resource specifies which rules can be used, but parsing and validating is handled automatically by the API. You can see examples here: ​

"with" parameter

The with query parameter is a special optional parameter used to describe which data the caller wants returned. This helps keep responses small and can address practical problems like only loading data when needed. See the Contact resource for a good example.

Controllers

The API should follow RESTful conventions where possible, controllers should be named after the model they are responsible for.