REST API Design

The philosophy behind RESTful APIs is that each object in the application domain should be addressable via a unique URL.

For example a clip with the id 1234 would have the URL

/api/3/clips/1234

We refer to this URL as the object’s path and it consists of number of elements:

/api   - api prefix
/3     - api version number
/clips - the 'endpoint'
/1234  - the 'selector'

All API URLs start with the ‘api’ prefix, to route the call to the correct handler, and the version number to allow the server to handle clients expecting particular versions of the API.

The next element, the  ‘endpoint’,  represents the collection of all items of a particular type stored on the server – in this case clips. The ‘selector’ (if present) selects a particular item from that collection. If there is no selector then the URL refers to the whole collection.

HTTP Methods

Up to now the examples have involved entering the URL of an API endpoint into a browser. When this is done  the browser sends an HTTP GET request to the endpoint. HTTP GET requests are used to retrieve data from the endpoint, but HTTP provides a number of other methods (or verbs) that are used by the REST API to signify the operation you wish to perform on the endpoint.

• GET – retrieve one or more objects from the endpoint
• POST – adds an object to the collection represented by the endpoint
• PUT – updates a specified object in the endpoint collection.
• DELETE – delete a specified object from the endpoint collection

To use these other methods you will typically need to access the API from code.