...

1. A resource is an abstraction of information or a concept. Choose a URI that incorporates the resource name to identify the information or concept. Resource names should be nouns. For example, the SDP Vocabulary Service includes the concept of a Survey to define data collection instruments. The resource name should include "survey" to indicate its meaning, e.g. a resource that provides a list of surveys could be https://sdp-v.services.cdc.gov/api/surveys  
2. Use plural nouns for consistency. For example, https://sdp-v.services.cdc.gov/api/surveys and https://sdp-v.services.cdc.gov/surveys/S-11 
3. Do not encode API version numbers in the URL. Cool URIs don't change, see the section on versioning for more information.
4. Support content negotiation (selection of the representation format - XML, JSON, etc.) via the HTTP Accept header. For convenience it is also acceptable to additionally support URL-based format specification, e.g. http://example.org/docs/1.xml to specify an XML representation of the http://example.org/docs/1 resource.
5. Do not include operation or action names in the URL, e.g. http://www.acme.com/products/new. While this style of URI is common in Web applications, where the example URI might identify a Web form that aids in creation of a new product, Web APIs should instead use URIs like http://www.acme.com/products in conjunction with a HTTP POST that includes a representation of the new resource to be created.
6. Filtering, sorting, searching, pagination and resource versions (not API versions) should be specified using query parameters. For example, https://sdp-v.services.cdc.gov/api/surveys?limit=100 where the limit query parameter is used to limit the number of items returned. This allows multiple such qualifiers to be used together without requiring complex hierarchies within the URI.

Examples of Bad URLs

...

Control Data

Control data defines the purpose of a message between components, such as the action being requested or the meaning of a response. For example, cache behavior can be modified by control data specified as HTTP Cache-Control header included in the request or response message. Etags are useful to help prevent simultaneous updates (optimistic locking) of a resource from overwriting each other. Control data using HTTP headers should be used appropriately. Below is an example of control data in a Request and Response

Request

GET /surveys HTTP/1.1
Host: sdp-v.services.cdc.gov
If-None-Match: "0eaac798-cb6a-41fd-ac7a-78f1a40945c6"

...

• 301 Move Permanently indicates that the URI of the requested resource has been changed and the new URI is provided in the Location header.
• 302 Found indicates that the resource is temporarily identified by a different URI (supplied in the Location header). New changes in the URI might be made in the future. Therefore, this same URI should be used by the client in future requests.
• 304 Not Modified indicates that request preconditions (e.g. If-Modified-Since or If-None-Match) were not met or the client has the response already in its cache. In both cases there is no need to transfer the same representation again. This response should be used for requests with GET or HEAD methods.

4xx (Client Error Category)

...

• 400 Bad Request indicates that the request by the client was not processed, as the server could not understand what the client is asking for.
• 401 Unauthorized indicates that the client is not allowed to access resources, and should re-request with the required credentials.
• 403 Forbidden indicates that the request is valid and the client is authenticated, but the client is not allowed to access the page or resource for any reason. E.g sometimes the authorized client is not allowed to access the directory on the server.
• 404 Not Found indicates that the requested resource is not available now.
• 406 Not Acceptable indicates that the server was unable to return a representation of the resource in the format requested by the client (in the request Accept header).
• 410 Gone indicates that the requested resource is no longer available which has been intentionally moved.
• 412 Precondition Failed indicates that access to the target resource has been denied. This happens with conditional requests on methods other than GET or HEAD when the condition defined by the If-Unmodified-Since or If-None-Match headers is not fulfilled. In that case, the request, usually an upload or a modification of a resource, cannot be made and this error response is sent back.
• 415 Unsupported Media Type indicates the media format of the requested data is not supported by the server, so the server is rejecting the request.

...

Hypermedia As The Engine Of Application State (HATEOAS)

HATEOAS introduces discoverability, providing a way of making a RESTful API self-documenting. The client needs no prior knowledge about how to interact with any particular resource beyond a generic understanding of hypermedia and detailed knowledge of the representation format in use and the link relationships used in that format.

The client enters a RESTful application through a simple fixed URL. All future actions the client may take are discovered within resource representations or HTTP headers returned from the server. The media types used for these representations, the link relations they may contain, and operations available on the resource are standardized. The client transitions through application states by selecting from the links within a representation or by manipulating the representation in other ways afforded by its media type. In this way, RESTful interaction is driven by hypermedia, rather than out-of-band information.

Benefits of HATEOS are:

1. They inform the client on what actions can be taken
2. Allows the server to change its URI scheme without breaking clients
3. New capabilities can be advertised by putting new links in the response

Guidelines:

1. Use links to allow clients to discover locations and operations
2. Use Hypermedia Link Relations to specify the relationship
3. Use the atom:link structure to capture links in representations

...

Strict-Transport-Security: max-age=31536000; includeSubDomains

Caching

HTTP Caching eases the load of the server that doesn’t need to serve all clients itself, and it improves performance as it takes less time to transmit the resource back to the client. Specify appropriate Cache Control headers based on your use case needs. Every request and response can define its own caching policies via the Cache-Control HTTP header. For requests, the directive specifies whether cached responses are permitted and under what circumstances. For responses, the directive specifies whether it can be cached, under what conditions and for how long. Below is a list of Cache-Control directive that can be used in HTTP requests and responses.

...

Compatibility is an important consideration since clients and servers are often the responsibility of different parties, there are often many more clients of an API than providers, and it can be difficult to upgrade all parties at the same time. The rest of this section describes approaches to versioning of APIs that follows Postel's Law. Additional material on application of Postel's law to the design of APIs is available in Jose Luis Ordiales's blog.

Versioning RESTful APIs

A RESTful API's contract is defined by the constraints specified in the Uniform Interface. The Uniform Interface comprises of these four constraints

...

• If additional fields are being added to the representation, then just add it to the representation. Clients and servers should ignore what they don’t understand and you don't need to version the API. Refer to Postel's Law. 
• If there are breaking changes to the representation, version the representation and use content negotiation to serve the right representation version to clients. For example, PIN code is changed to ZIP code in Address resource representation, then the Address representation's version should be increased to the next version. The same guideline will apply when the hypermedia links are modified. The example of how content negotiation can be done using the Accept header is described in the media type versioning section. Handling changes using media type versioning strategy is the recommended approach.
• If you want to change the meaning of a resource then resist the urge to change an existing resource, instead create a new one with a different URI.

...

1. No Versioning: New resources and functionality can be added without requiring any versioning provided existing clients can continue to work based on the pre-existing functionality.

Adding new content to resource representations does not represent a breaking change if it does not impact existing clients. For example, the representation of a survey resource might be:

...

The W3C TAG published a guide to extending and versioning XML schemas that contains practical advice on the use of XML features for versioning XML-based representations with a focus on forwards and backwards compatibility.

Adding new query parameters does not represent a breaking change if it does not impact existing clients. For example, in the first version of an API, a survey might be identified using the following URI:

https://sdp-v.services.cdc.gov/api/surveys/10

In a future version of the API, it may be desirable to limit the size of the returned response by adding a verbose boolean parameter, e.g.:

https://sdp-v.services.cdc.gov/api/surveys/10?verbose=false

Addition of this new verbose query parameter can be done in a non-breaking way by defaulting its value so that omitting it would produce the same result as the prior version of the API. Existing clients that don't know about the parameter (and don't include it the URIs they use) can continue to function without change, new clients that are aware of the parameter can use it to control the size of the returned response. This approach also complies with the guidance that cool URIs don't change since existing URIs for a resource continue to work unchanged.

The same kind of approach can be taken to renaming query parameters or supporting new values for those parameters. Rather than removing existing parameters or changing the meaning of existing parameters or parameter values, continue to support the existing parameters and parameter values and add support for new parameters or parameter values.

2. Media Type Versioning: When consuming a RESTful API a client specifies the format of content that it expects as part of HTTP GET request using the Accept header. The client can specify XML, JSON, or some other format that it expects in the body of the response. Additionally, the Accept header can also be used to specify a custom media type that allows the client application to specify the version of the resource representation it expects in the response. For a breaking change to the survey representation, this approach is shown below.

Version 1: 

Request:
GET /surveys/1 HTTP/1.1
Accept: application/vnd.sdp-v-services+json;v=1.0

Response:
HTTP/1.1 200 OK
Content-Type:  application/vnd.sdp-v-services+json;v=1.0; charset=utf-8 
{"id":1, "name":"Salmonella outbreak","creator":"John Doe"}

Version 2:

Request: 
GET /surveys/1 HTTP/1.1 
Accept: application/vnd.sdp-v-services+json;v=2.0

Response: 
HTTP/1.1 200 OK 
Content-Type:  application/vnd.sdp-v-services+json;v=2.0; charset=utf-8 
{"id":1, "name":"Salmonella outbreak","creator":{"firstname":"John", "lastname": "Doe"}}

...

It is recommended that APIs that require authentication and authorization utilize OAuth for that purpose. Use of OAuth to secure CDC APIs is detailed in Using OAuth to Secure CDC APIs.

API Definition

APIs need to be described using standard, language-agnostic interface which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. Consumer of API should be able understand and interact with the service with a minimal amount of implementation logic. OpenAPI Specification is the industry standard for defining and describing APIs. APIs should be defined and described using latest version of OpenAPI Specification.

...