...
This is the initial draft of recommended best practices for API development and consumption at Columbia.
content below is out of date and needs to be updated.
Overview
The central feature of REST architecture is the emphasis on a uniform interface between components
...
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 for resource(s) in collection
Fields List GET https://<domain-app>.api.columbia.edu/{app}/{v}/{resources}?fields={“field1”,”field2”,…,”fieldN”}
Note that the above definitions have reserved the following query parameter names:
...
Basic Operation APIs are shown with examples (for the directory app, version 1):
GET https://<domain-app>.api.columbia.edu/v1/people people - Retrieves a list of People from directory
GET https://<domain-app>.api.columbia.edu/v1/people/jd1234 jd1234 - Retrieves John Doe's information based on UNI
POST https://<domain-app>.api.columbia.edu/v1/people people - Creates a new employee using JSON payload
PUT https://<domain-app>.api.columbia.edu/v1/people/jd1234 jd1234 - Updates John Doe's info in Directory
PATCH https://<domain-app>.api.columbia.edu/v1/people/jd1234 jd1234 - Partially updates the John Doe's info in Directory
DELETE https://<domain-app>.api.columbia.edu/v1/people/jd1234 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” “asc” - Search for people with surnames starting with Smith
...
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: An endpoint used to discover the types of resources used by this app.
GET https://<domain-app>.api.columbia.edu/{v}/types : (schemas) Introspect resource and attribute definitions.
...
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/types
SSL Everywhere
Always use SSL, no exceptions. This is enforced at the f5 load balancer (api.columbia.edu) which terminates SSL sessions.
...