API Design Guide

Cisco

API Lifecycle

Versioning

How to handle API versioning

Collection Resources

Filtering

How to select some resources in a collection

Collection

What is a collection (set) of resources

Pagination

How to retrieve a range of resources in a collection

Data

Date and Time

How to deal with date and time data

  • 3.3 Representations
    3.3.8 Date and time fields MUST be represented as strings and formatted according to RFC-3339

Data format

which data format use

Null data

How to deal with null data

Error handling

Error format

How to provide information about errors

HTTP Methods

HTTP methods

General information about HTTP methods usage

POST

The POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. The data POSTed might be, for example, an annotation for existing resources; a message for a bulletin board, newsgroup, mailing list, or comment thread; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database.

PUT

The PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI.

DELETE

The DELETE method deletes the specified resource.

PATCH

The PATCH method applies partial modifications to a resource.

HEAD

The HEAD method asks for a response identical to that of a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content.

GET

The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect.

Forbidden methods alternatives

What to do when only possible HTTP methods are POST and GET

OPTIONS

The OPTIONS method returns the HTTP methods that the server supports for the specified URL. This can be used to check the functionality of a web server by requesting ‘*’ instead of a specific resource.

HTTP Protocol

HTTP Statuses

General information about HTTP statuses usage

HTTP Headers

How to use standard or custom HTTP headers

Caching

How to use and provide relevant caching informations

Content negociation and media types

How to describe your API data format and/or propose different formats (like json, yaml, xml atom, …)

Hypermedia

Hypermedia

How to use hypermedia

  • 3.3 Representations
    3.3.3 A resource identifier labeled "url" MUST be present in all RESTful API resource representations

Hypermedia (read)

How to use hypermedia to read data

  • 3.3 Representations
    3.3.3 A resource identifier labeled "url" MUST be present in all RESTful API resource representations

Miscellaneous

Undo

How to undo things

  • 3.6 HTTP Verbs
    *3.6.4.3 *The POST verb MAY be used to reverse the soft-delete of a resource, using an undelete parameter

API chaining

How to chain API call in internal systems

Documentation

How to produce and/or propose API documentation

Naming

Case

Which case (lowercase, camelCase, …) to use and when

Naming

How to name things

  • 3.3 Representations
    3.3.11 With regard to JSON representation property names, and URL query parameters, services SHOULD...

Resources

Dereference Relationships

How to load a resource and its linked resources in one call

  • 3.6.3 GET
    If a service supports the fields parameter, then a value of @reference, @narrow, or @wide SHOULD...

Update resource partially

How to udate partially a resource

Delete resource

How to delete resources

Batch Bulk

How to handle batch/bulk processing/creation/update/… (e.g. handle multiple resources at conce)

Action resource

How to use action resource (e.g. resources like /cancel or /approve)

Replace resource

How to replace (or update fully) a resource

Create resource with a specific ID

How to create resource with a provided id

Create resource

How to create resources

Update resource

How to update a resource

Retrieve resource partially

How to retrieve partially a resource

Retrieve resource

How to retrieve a resource

Resource

General informations about resources

URL format

How to design URLs

ID with semantic

Using meaningful ids (like me)

Security

Security

Security concerns