Content Comparison

...

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}/resourceTypes: openapi: 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)

...