API Design Guide

April 9th, 2017

Use RESTful service URLs

Under REST principles, a URL identifies a resource. The following URL design patterns are considered REST best practices:

  • URLs should include nouns, not verbs.
  • Use plural nouns only for consistency (no singular nouns).
  • Use HTTP methods (HTTP/1.1) to operate on these resources:
  • Use HTTP response status codes to represent the outcome of operations on resources.

Response Http Status Code

  • 200 OK
  • 400 Bad Request
  • 500 Internal Server Error

Other commonly seen codes include:

  • 201 Created
  • 204 No Content
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found

jQuery Ajax Request

  • type: ‘GET’ —- dataType: ‘xml|json|script|text|html’ -> response http status code: 200 / 404
  • type: ‘POST’ —– dataType: ‘xml|json’ -> response http status code: 201 (created) / 405 (Method Not Allowed)
  • type: ‘PUT’ —— dataType: ‘xml|json’ -> response http status code: 200 / 404
  • type: ‘DELETE’ —— if return 204, dataType should not be ‘json’ -> response http status code: 200 / 404

Good RESTful URL examples

List of magazines:

GET /api/v1/magazines.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Filtering and sorting are server-side operations on resources:

GET /api/v1/magazines.json?year=2011&sort=desc HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

A single magazine in JSON format:

GET /api/v1/magazines/1234.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

All articles in (or belonging to) this magazine:

GET /api/v1/magazines/1234/articles.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

All articles in this magazine in XML format:

GET /api/v1/magazines/1234/articles.xml HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Specify query parameters in a comma separated list:

GET /api/v1/magazines/1234.json?fields=title,subtitle,date HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript

Add a new article to a particular magazine:

POST /api/v1/magazines/1234/articles.json HTTP/1.1
Host: www.example.gov.au
Accept: application/json, text/javascript