Purpose

The purpose of this guide is to encourage consistency in the design and implementation of REST Services for campus consumption. However, experience has shown that opinions, preferences, and tastes differ among designers and developers; so this guide will avoid being overly prescriptive, allowing for the evolution of the standards as experience dictates. Peer review is a good practice and usually, leads to better overall solutions.

Disclaimer

This design guide is limited to the discussion of REST services. In addition, all the examples given below are examples only. The use of an example does not indicate that the resource discussed is currently available or will become available in the future.

Benefits of REST Style

REST provides 5 "constraints" that help guide toward a good API

1. Client–server - Separation of concerns is the principle behind the client-server constraints. By separating the user interface concerns from the data provider concerns, we improve the ability to create user interfaces across multiple platforms and improve scalability by simplifying the server components. Perhaps most significant to the Web, however, is that the separation allows the components to evolve independently, thus supporting the Internet-scale requirement of multiple organizational domains.
2. Stateless: Statelessness means that state is maintained on the client. This makes every request/response transaction independent. Stateless communications enable clients to recover from network errors, clients and servers can come and go without corrupting state, and new processing nodes can be attached without complex state management.
3. Cacheable - Cache control at multiple levels (client, server, intermediary) – because state exists in only one place. Caching at multiple levels decreases latency, bandwidth, and cost.
4. Uniform interface - This includes identifying resources, manipulation of resources, describing message types and application state transition. Resources are identified by URIs. These URI's serve as an abstraction and should not change often. HTTP verbs (e.g. GET, PUT DELETE) describe how to manipulate resources. Server state transition occurs only through actions that are dynamically identified within hypermedia by the server  Hypermedia protects the server from being locked into a URI scheme.
5. Layered system - Limits the complexity of implementing each layer and allows for multiple layers of security.

URI

There are three parts to the URI of a REST service: the host, the API, and the desired resource.

{host}/{api-version}/{resource}

Each part may be comprised of more granular elements and will be described in their respective sections.

The entire URI should be lowercase.

The host is made up of a {base} and an {api context} : {base}/{api_context}

{base} = http(s)://api[-dev|-qa].ucop.edu

The -dev and –qa indicators represent stages in the development and delivery of the service. When no indicator is present then the stage is production.

{api_context} is a context for the resource.

API Version

API Version indicates breaking change in the interface (request or response) or functionality that prevents existing consumers from consuming this API successfully.

• Version only when needed. A new version of API also requires multiple runtime binaries and many times, backend database changes.
• Work with clients to see if they can be upgraded without increasing the version
• Support at the most 2 versions
• Version if the response has breaking change as well.

How to version:

There are different ways to version an API. Various techniques are based on indicating version number in

• Headers
• URLs
• Headers & URLs both, using a Hybrid approach. Use the latest version by default unless a specific version is provided in the header or in URL

It is recommended to use URL based versioning as it specifically indicates what version is being used by the consumer. A version number should be appended to the host to allow for versioning of the resources.

Version Format:

There are different ways to format the version. The recommendation is to use V1, V2, etc... (or v1). if the API Gateway software does not allow use of non-numeric version numbers, use 1, 2,3 etc.

Resource

Naming Convention

• URI MUST use snake case
• Resources MUST use snake case
• Query Parameter Keys MUST use camel case.
  • Using camel case will reduce mapping effort between query parameter and backend variables
• Query Parameters Values are application specific
• Request Body MUST use camelCase
  • Follow Google’s JSON guidelines
• Response Body MUST camelCase
  • Follow Google’s JSON guidelines
• Resource names SHOULD be plural
  • e.g. dogs instead of dog
• Resources SHOULD be nouns and not verbs

Identification

A resource is the entity on which an operation is performed. For instance - Create, Read, Update, Delete

• Concrete resources are better than abstract
  • e.g. /dogs better than /animal
• Two URLs per resource are needed
  • The first one is for a collection. Use plural to refer to collection
    • e.g.  /applications,  /dogs etc.
  •  The second one is for an instance of a resource 
    • e.g. /applications/a1b2, /dogs/{id}
• If more than one identifier is needed to identify a resource, they MUST be concatenated with commas
  • e.g. /classes/CSE,100,SP18 instead of /classes/CSE/100/SP18
• When there are multiple types of resource identifiers, it is a good practice to qualify the identifier.
  • e.g. /employees/employee_id=123 or /employees/racfid=AAAZZZ

Linking

Linking is fundamental to scalability and flexibility of the system

MANY to MANY Relationship (example to be added later)

Represent the links separately

e.g. users and groups have many to many relations

Information about users/1 will return,

users/1
users/1/groups/1

users/1/groups/2
groups/1

Dealing with relations

If a relationship can only exist within another resource, RESTful principles provide useful guidance. e.g. A Class consists of a number of sections. These sections can be logically mapped to the /classes endpoint as follows:

• GET /classes/12/sections - Retrieves list of sections for class 12

Limiting which fields are returned by the API

The API consumer does not always need the full representation of a resource. The ability to select and choose returned fields goes a long way in letting the API consumer minimize network traffic and speed up their own usage of the API.

Using a comma-separated list of fields to include in the fields query parameter allows you to restrict what data is returned.  For example, the following request would retrieve just enough information to display a sorted listing of open tickets:

GET /tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

Search and other Algorithms

Use a combination of collection and query parameters to filter out information appropriately.

Efficiency

• Query parameter use ?expand=xyz to expand the xyz resource
• Alternately, return fields=givenName, surname,directory(name)
• Should support parameters offset and limit

you can also add nested partial fields

in the following format

fields?=id,customer(id,name)

in this case, return object will in the following format

[{
    "id":"12",
    "customer":{
      "id": "232",
      "name" :"abc corp"
    }
},
...
]

Request

The API MUST use proper HTTP methods, and operation idempotency* MUST be respected. Below is a list of methods that APIs SHOULD support. Not all resources will support all methods, but all resources using the methods below MUST conform to their usage.

GET /dogs

GET /dogs/10

POST /dogs

PUT /dogs/10

PATCH /dogs/10

DELETE /dogs/10

OPTIONS /dogs

*Idempotence is the idea that a client can make the same call repeatedly while producing the same result. In other words, making multiple identical requests has the same effect as making a single request.

**An operation is considered safe if the operation does not significantly alter the state of the application

Responses need to contain either JSON or XML. Ideally, let consumers provide their preference by specifying an accept header in order of preference.

Response

Success Scenario

• 200 if you want send some additional data in the Response.
• 201 Response to a POST that results in a creation of a resource. Should be combined with a Location header pointing to the location of the new resource.
• 202 Operation deleted has not been committed yet.
• 204 Request successful but no content.
• 304 Not Modified - Used in response to conditional GET calls to reduce bandwidth usage. If used, must set the Date, Content-Location, ETag headers to what they would have been on a regular GET call. There must be no response body.

ERRORS and Exceptions:

Errors should be as descriptive as possible. The following format is recommended

JSON payload

{
  "message": string,
  "developerMessage": string,
  "moreInformation": string,
  "errors": [
    {
      "message": string
    }
  ],
  "code": string
}

Note:

• Either message or message array needs to exist.
• All other elements are optional and if the value is null, the element should be omitted. An element should not be an empty string.
• Use an array of messages to capture multiple validation errors.
• 400  The request is malformed, such as if the body does not parse 
• 401  Unauthenticated. When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser
• 403  The request is a legal request but user is unauthorized
• 404  Not Found - When a non-existent resource is requested
• 405  When an HTTP method is being requested that isn't allowed for the authenticated user. 
• 409  Resource Conflict can be possible in complex systems. It can be caused by fulfilling the request. Duplicate entries, deleting root objects when cascade-delete not supported are a couple of examples.
• 410  Gone - Indicates that the resource at this endpoint is no longer available. Useful as a blanket response for old API versions
• 415  Unsupported Media Type - If incorrect content type was provided as part of the request
• 422  Unprocessable Entity - Used for validation errors
• 429  Too Many Requests - When a request is rejected due to rate limiting

HTTP Error Code 

Client error codes

Server Error Codes

• 500 INTERNAL SERVER ERROR – The general catch-all error when the server-side throws an exception
• 501, Not Implemented. The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource
• 503 Service Unavailable. The server is currently unable to handle the request due to a temporary overloading or maintenance of the serve

Business Exceptions

While none of the HTTP response codes match well with a business rule exception, use of the HTTP code 403 indicates that the server is refusing to fulfill the request.  This status code can be used when a business rule won’t allow fulfillment of the request - e.g. Enrollment when a class is full.

Timestamp

Per ISO 8601 guidelines, always use UTC time zone.

Security 

It is recommended to follow all of OWASP’s REST security guidelines and to specifically pay careful attention to:

• Always use SSL. No exceptions
• Keep it stateless as much as possible
• Avoid sequential numbers for the resource ID

Appendix

Additional articles on best practices for designing RESTful APIs

1. Roy Fielding’s dissertation on REST https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
2. Google -
   1. Google's JSON guide - https://google.github.io/styleguide/jsoncstyleguide.xmll
   2. Google's API guide - https://cloud.google.com/apis/design/
3. Microsoft's API Guideline - https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md
4. OWASP’s REST Security guidelines - https://www.owasp.org/index.php/REST_Security_Cheat_Sheet
5. http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
6. http://blog.octo.com/en/design-a-rest-api/
7. https://developer.byu.edu/docs/design-api/university-api-standard

Glossary

HATEOAS (Hypermedia as the Engine of Application State) is a constraint of the REST application architecture that keeps the RESTful style architecture unique from most other network application architectures. The term “hypermedia” refers to any content that contains links to other forms of media such as images, movies, and text.