...
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.
...
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
sortBy
sortOrdersort
fields
Please use these as shown in the example. Additional query parameters can of course be usedFor 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):
...
The following metadata and special resources should be available for every application:
GET https://<domain-app>.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://<domain-app>.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://<domain-app>.api.columbia.edu/v1/resourceTypesschemas - JSON-Schema.org schemas.
- GET https:// <domain-app>.
- 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)
...