...
We at Columbia choose version to be part of URL:
https://<domain-app>.api.columbia.edu/{v}/{resources}
Version should be kept to the right of the app name. We choose to prefix 'v' as part of version and use only the ordinal numbers, like “v1”, “v2”, etc.
...
Use the following example patterns as a guide. Implementing every HTTP method and complex search query parameters is not required but should follow these patterns when used.
GET https://<domain-app>.api.columbia.edu/{v}/{resources} - Retrieves a list of resources
GET https://<domain-app>.api.columbia.edu/{v}/{resources}/{id} - Retrieves a specific resource
POST https://<domain-app>.api.columbia.edu/{v}/{resources} - Creates a new resource using JSON payload
PUT https://<domain-app>.api.columbia.edu/{v}/{resources}/{id} - Updates resource info
PATCH https://<domain-app>.api.columbia.edu/{v}/{resources}/{id} - Partially updates the resource
DELETE https://<domain-app>.api.columbia.edu/{v}/{resources}/{id} - Deletes the resource
Search GET https://<domain-app>.api.columbia.edu/{v}/{resources}?filter=[{”{attribute1}”,”{op1}”,”{value1}”},…,{”{attribute2}”,”{op2}”,”{value2}”}]&sortBy={attribute}&sortOrder={asc|desc} [search]={keyword}&sort={attribute} - Search for resource(s) in collection
Fields Sparse Fieldsets List GET https://<domain-app>.api.columbia.edu/{app}/{v}/{resources}?fields={“field1”,”field2”[{resource}]=field1,field2,…,”fieldN”}fieldN
Note that the above definitions have reserved use the following query parameter names:
filter
sortBysort
sortOrder
fields
Please use these as shown in the example. Additional query parameters can of course be used.For more complete details, see the JSON API Architecture Pattern.
API Pattern Example
Basic Operation APIs are shown with examples (for the directory app, version 1):
GET https://<domain-app>.api.columbia.edu/directory/v1/people - Retrieves a list of People from directory
GET https://<domain-app>.api.columbia.edu/v1/people/jd1234 - Retrieves John Doe's information based on UNI
POST https://<domain-app>.api.columbia.edu/v1/people - Creates a new employee using JSON payload
PUT https://<domain-app>.api.columbia.edu/v1/people/jd1234 - Updates John Doe's info in Directory
PATCH https://<domain-app>.api.columbia.edu/v1/people/jd1234 - Partially updates the John Doe's info in Directory
DELETE https://<domain-app>.api.columbia.edu/v1/people/jd1234 - Deletes John Doe's record in directory
Search GET https://<domain-app>.api.columbia.edu/v1/people?filter=[{“surname”,”like”,”Smith*”}]&sortBy=“surname”&sortOrder=“asc” - Search for people with surnames starting with Smith
...
The following metadata and special resources should be available for every application:
GET https://api.columbia.edu/{v}/console: API console (MuleSoft APIkit).GET https://<domain-app>.api.columbia.edu/{v}/resourceTypesopenapi: An endpoint used to discover the types of resources used by obtain the OpenAPI (OAS) 3.0 schema for this app.
GET https://api.columbia.edu/{v}/types : (schemas) Introspect resource and attribute definitions.
Enterprise Metadata Resources (DRAFT)
A top-level Columbia University enterprise metadata directory will contain the list of available types (schemas) and resource types (item, collection, etc.) that are used by the various applications:
GET https://api.columbia.edu/v1/resourceTypesschemas - JSON-Schema.org schemas.
- GET https://api.columbia.edu/ v1/types
- scopes - definitions of available custom OAuth2 scopes
SSL Everywhere
Always use SSL, no exceptions. This is enforced at the f5 load balancer (https://<domain-app>.api.columbia.edu) which terminates SSL sessions.
...
Always provide good API documentation. The document should be easy to find and publicly accessible to the consumers. Documentation should consist of:
A RAML 1OpenAPI Specification (OAS) 3.0 API definition that documents the API in general, the specific resources and the methods that operate on them, Meanings of OAuth 2.0 scopes, etc.
An API Notebook example An example walkthrough of using the API.References to the schemas and logical data model underlying the API. This should be in the RAML. See also API Metadata, above, perhaps using a Jupyter Notebook.
JSON only responses
At Columbia JSON responses are preferred responses from API
...
For APIs which returns large number of records, link headers links should be used for pagination into the previous and next pages. For example:
...
{
"links": {
"first": "https://app.api...
.columbia.edu/v1...
/things/?page...
[number]=1",
"last": "https://app.api.columbia.edu/v1/things/?page[number]=448",
"next": "https://app.api.columbia.edu/v1...
/things/?page...
[number]=2",
"prev": null
},
"data": [ ... ]
}Rate Limiting
It is good practice to add rate limiting to an API, use HTTP status code 429 Too Many Requests
...
An API should provide a useful error message in a known consumable format like JSON. The error message should contain its own set of fields, for example:
{
"errors": [
{
"...
detail": "...
Authentication credentials were not provided.",
...
"status": ...
"401",
"source": {
...
"pointer": "...
/data"
},
"code": "not_authenticated"
}
]
}N.B. See JSON API error objects. There is more discussion needed around a recommended standard error response.
HTTP Codes
API should return HTTP defined status codes, which helps consumer of API route their responses accordingly, see below for the list (HTTP Status code)
...