Building and using APIs

Recommended

Agencies are encouraged to make all digital services available as an API,

Recommended

Agencies are encouraged to deliver all APIs following ‘Pragmatic REST’ (Representational state transfer) principles detailed below.

• Use RESTful service URLs
  • Versioning
  • Formats
  • URL Depth
  • API Payload formats
  • API Payload format encoding
  • Good RESTful URL examples
  • Bad RESTful URL examples
• Use HTTP methods and status codes
  • Examples
  • HTTP response principles
  • Provide error responses
• Use versions
• Batching results
• Mock behaviour
  • Example 1 - GET mock list of magazines
  • Example 2 - GET individual mock magazine
  • Example 3 - POST article to mock magazine
• Support cross-domain mashups with CORS
• Management state with HATEOAS
• Document your API
• Register your API

The content in this guide has been adapted from: https://github.com/WhiteHouse/api-standards