Introduction

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.

Expand

title	Contents

Table of Contents

Section

Panel

borderColor	#ffab00
bgColor	white
titleColor	white
borderWidth	1
titleBGColor	#ffab00
borderStyle	solid

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

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.

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.

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.

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.

Layered system - Limits the complexity of implementing each layer and allows for multiple layers of security.

Warning

Checklist to avoid ERRORS

This is the short version of this document. If you fail to follow these your API will may experience problems and/or not be deemed acceptable. In either case it will have to be deleted and rebuilt. Name, Context and Version can not be changed after the API is created.

Name: Use only letters, numbers and underscores.
Context: Use only a leading /, lowercase ascii letters, numbers and underscores
Version: Use only numbers, dots (.) and an optional "v" prefix.

Section

Introduction

Panel

borderColor	#ffab00
bgColor	white
titleColor	white
borderWidth	1
titleBGColor	#ffab00
borderStyle	solid

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

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.
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.
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.
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.
Layered system - Limits the complexity of implementing each layer and allows for multiple layers of security.

Section

Name, Version and Context

Panel

borderColor	#ffab00
borderWidth	1
borderStyle	solid

The Name, Context and Version are critical fields the uniquely identify an API.

They can not be changed and should be chosen very carefully.

At UCSD we are managing APIs with WSO2's API Manager and there are some additional requirements / problems that require special attention. A known bug is that the UI is too permissive in what's allowed in these fields, which can cause errors when publishing or later.

Name

This is the "Display Name" of the API. It is shown in the API Store and Publisher. It should be the "Human Readable" name of your API

UCSD REQUREMENTS:

Use UpperCamelCase
Use only letters. Numbers and underscores are allowed where necessary.
Use a name that uniquely identifies your API within UCSD.
Avoid long and short names. 2-3 words is common.
DO NOT INCLUDE THE VERSION IN THE NAME
Avoid including "API" in the name as it's redundant.

Context

This is the "url name" of the API. It is what is included in the URL when calling the API. It should be the "Machine Readable" name of your API. The Name and Context of the API should be almost identical, given one a user should be able to easily identify the other.

UCSD REQUREMENTS:

Only a leading /, lowercase ascii letters, numbers and underscores.
Take the Name, lowercase it and optionally add underscores. Eg. PreferredPronoun → /preferredpronoun or /preferred_pronoun
DO NOT INCLUDE THE VERSION IN THE CONTEXT.
The WSO2 API Manager supports several context formats; UCSD only recommends using the basic format (single leading /, no curly braces). Invalid contexts cause a bug that causes the API to fail to deploy in which case it must be deleted and recreated.

Version

The WSO2 API manager treats multiple versions of an API as separate APIs. Therefor the Version is used to identify which one a user is referencing. See below for more information on how Version should be used.

UCSD REQUREMENTS:

Use numbers, dots (.) and an optional "v" prefix.
The recommended format is a single number eg: "1". See below for reasoning.

Example

Name: PreferredPronoun
Context: preferredpronoun
Version: 1

Section

URLs

Panel

borderColor	#ffab00
bgColor	white
titleColor	white
borderWidth	1
titleBGColor	#ffab00
borderStyle	solid

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

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

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

Each of the URL elements listed above MUST use snake_case

Host

The host will be in the following format:

Info

icon	false

https://api[-qa].ucsd.edu

The –qa indicator represents a non-production deployment. When no indicator is present then the stage is production.

Context

The API context is used to determine which API an incoming request is attempting to access. The API Context MUST be unique and snake_case. When viewing APIs in the store and publisher the API Name is used. The API Name should be unique and human friendly. It is our recommendation that the context be a URL-friendly version of your API Name. Often we suggest removing special characters and setting it to lower case. Some long API Names can also be abbreviated. It should be clear which API Name and API Context is referencing, so when a developer is reading code and finds the URL that is invoked, they can find that API in the store.

API Version

The API version is used to determine which iteration of an API an incoming request is attempting to access. It is used in conjunction with the API context. 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:

It is recommended to format the version like: v1, v2, etc. Optionally you can omit the “v” or include a minor version like: v1.2, 1.2, etc. However, minor versions shouldn’t cause breaking changes so minor versioning in the url is discouraged.

Resource

The resource URL element specifies an entity in the current context. A resource by itself represents a collection of entities. You can refer to a single entity by specifying a unique identifier.

General Conventions

Resources MUST use snake_case
Resources SHOULD be nouns and not verbs
Resources SHOULD be plural
Concrete resources are better than abstract

e.g. /dogs better than /animal

Single Entity Resource

A specific resource entity can be targeted by adding the identifier to the URL. For example:

Info

icon	false

https://api.ucsd.edu/context/v1/articles/1234

The identifier MUST uniquely identify a specific resource entity.

Compound Resource Identifiers

If more than one identifier is needed to identify a resource, they MUST be concatenated with commas:

Info

icon	false

/classes/CSE,100,SP18 instead of /classes/CSE/100/SP18SP18 Note: In the API manager and the OpenAPI specification, these should still be indicated as separate parameters e.g. /classes/{subjectCode},{courseNumber},{termCode} instead of /classes/{compoundId}

Qualified Resource Identifiers

When there are multiple types of resource identifiers, it is a good practice to qualify the identifier.

Info

icon	false

/employees/employee_id=123 or /employees/racfid=AAAZZZ

Sub Resources

Sub resources are used to interact with entities that can be uniquely identified by a higher level resource and have a direct relationship to the higher level resource. For example:

Info

icon	false

https://api.ucsd.edu/context/v1/articles/1234/comments

This sub resource could be used to create a comment and associate it with an article.

Sub resources can also be identified with the same rules as top-level resources. For example:

Info

icon	false

https://api.ucsd.edu/context/v1/articles/1234/comments/1

Query Parameters

Query parameters can be used to specify the desired format of a response, for example: filtering, paging, sorting, etc. Query parameters MUST be camelCase.

...

Section

Resource representation

Panel

borderColor	#ffab00
bgColor	white
titleColor	white
borderWidth	1
titleBGColor	#ffab00
borderStyle	solid

It is recommended to use the HAL specification to represent responses in json or xml. HAL provides a set of conventions to express HATEOAS linking consistently.

Content negotiation

Content negotiation allows an API to provide multiple representations of a resource with the same URL. Two headers primarily used to enable this are Accept and Content-Type.

Accept - used by the client to specify which representation type is preferred in the response when there are multiple options available.
Content-Type - used by both the client and API to specify the representation of the request / response bodies.

Single resource

Single entity resources are targeted with urls that end in a unique identifier. For example:

Info

icon	false

https://api.ucsd.edu/context/v1/articles/1234

Resources are composed of name / value pairs where the values can be basic data types, objects, or arrays.

Basic data types

Strings:

Code Block
{ "title" : "REST API Guidelines" }

Numbers:

Code Block
{ "integer" : 1234, "negativeInteger" : -1234, "decimal" : 1234.01, "scientificNotation" : 1.2E+3 }

Boolean:

Code Block
{ "flag" : true }

Date/Time:

Date and time formats MUST follow the ISO8601 format specified in RFC3339 Section 5.6. Examples:

Code Block

{
	"date" : "2019-03-25",
	"timeLocal" : "13:30:57",
	"timeUTC" : "13:30:57Z",
	"timePSTOffset" : "13:30:57-08:00",
	"dateTimeUTC" : "2019-03-25T13:30:57Z",
	"dateTimePSTOffset" : "2019-03-25T13:30:57-08:00" 
}

Objects

Resources can have attributes values represented as other objects. If object is a sub-resource, meaning that can be specifically accessed via a URL, then it SHOULD be listed under the _embedded attribute following the HAL specification. A self link should be provided as well for easy access to the sub-resource.

Arrays

Attributes values can also be arrays. Arrays are collections of homogeneous values. The values can be basic data types or objects.

Links

Links are used to provide possible actions that can be made on a resource given its current state. More information can be found later in this document in the Links section.

Collections of resources

Resource collections are targeted with URLs that don’t specify a single resource with an identifier. For example:

Info

icon	false

https://api.ucsd.edu/context/v1/articles

Even if a filtering option is provided that results in a single resource, an array of resources should still be expected by the user agent. Collections of resources SHOULD be listed under the _embedded attribute, following the HAL specification, indicating that individual resources can be directly accessed via a self URL.

If the resources in the collection are large, then a reduced representation can be used that only contains the minimum attributes necessary for identification. The reduced resources MUST be accompanied by a self link to retrieve the full resource by itself.

Paging

It is recommended to provide paging options on large collections of resources to let the user agent limit the number of resources retrieved at one time. Additionally, links SHOULD be provided to facilitate the traversal of the paged collection.

More information can be found later in the document under the Pagination section.

Sorting

It is recommended to provide sorting options on large collections of resources. Even if sorting options are not provided, it is recommended to specifically order the collection by default for consistent responses.

More information can be found later in the document under the Sorting section.

Filtering

It is recommended to provided filtering options on large collections of resources.

More information can be found later in the document under the Filtering section.

...

Page Comparison

Versions Compared

Old Version 47

New Version Current

Key

Introduction

Purpose

Disclaimer

Benefits of REST Style

Checklist to avoid ERRORS

Introduction

Purpose

Disclaimer

Benefits of REST Style

Name, Version and Context

Name

Context

Version

Example

URLs

Host

Context

API Version

How to version:

Version Format:

Resource

General Conventions

Single Entity Resource

Compound Resource Identifiers

Qualified Resource Identifiers

Sub Resources

Query Parameters

Resource representation

Content negotiation

Single resource

Basic data types

Strings:

Numbers:

Boolean:

Date/Time:

Objects

Arrays

Links

Collections of resources

Paging

Sorting

Filtering