Pragmatic RESTful API Design

Chris Dail - @chrisdail

Director, Software Engineering at EMC


  • This is a pragmatic approach to REST (not a dogmatic one).
  • Ideas here are simply my opinion. I favour user experience and developer sanity over idealogical 'correctness'.
  • There is no REST spec or standard (but there is for HTTP)
  • Enterprise Software and Products vs SaaS

We love to think our products will solve all customer problems but this is not realistic

Why APIs?

  • Customer's don't want a product; they want a solution to their problem.
  • APIs allow integrating your product into the customer's solution.
  • Prevents the feeling of 'lock in'

v1.0 Feature

  • Most companies discover they need an API long after v1.0
  • Often an afterthough and maybe not given the attention it needs


  • Distributed applications, Netflix
  • Applications build with small decoupled, self-contained components
  • Each component handles a single job
  • Components communicate with each other via well established APIs

What Kind of API do I need?

What is REST?

Representational State Transfer

“HTTP based RESTful APIs are defined with these aspects: base URI, such as an Internet media type for the data. This is often JSON but can be any other valid Internet media type (e.g. XML, Atom, microformats, images, etc.) standard HTTP methods (e.g., GET, PUT, POST, or DELETE)” - Wikipedia

Or simply...

  • Web APIs
  • Web Services


  • Universal language, the Web
  • Universally available protocol, HTTP
  • Name one programming language that cannot talk to an HTTP server

Elements to a Good API

  • Features (I'll assume you have this covered)
  • User Experience - Know your user
  • Great Documentation

User Experience

  • External Consistency - Does it work like other APIs
  • Internal Consistency - Is the API consistent within itself


  • Resource Oriented
  • Nouns not Verbs
  • Pluralize Resources
  • Lower case, hypen separated
  • Short segments (1-2 words)
  • Top level component (when API gets big)

            /storage-systems     # Storage or Systems is not specific enough
            /foo/things          # 'foo' component allows multiple /things

Query Parameters

  • Used for optional parameters, options, search, filter, paging
  • Should never be required - Sensible Defaults
  • Data format case
  • Short (1-2 words)


CamelCase vs snake_case

  • vi vs emacs
  • Consistency!

Data Formats

  • JSON First, XML if required
  • Case Consistency with all formats
  • Keep fields short (1-3 words)
  • Handle Collections Differently

              "things: [
                { },
                { }

Field Formatting

  • Numbers as numbers
      // This
      "size_gb": 10
      // Not this
      "size": "10gb"
  • Dates ISO 8601 (xsd:dateTime, JavaScript standard)

Read vs Write data models

  • Command Query Responsibility Segregation (CQRS)
  • Separate models for read/write
  • Example: ID is required for update, but not create
  • Example: Password required on create, not part of read


  • Self-describing relationships and capabilities
  • HATEOAS - Links as part of data
  • Link Headers

            GET /widgets/12
            Link: <https://host/v1/widgets/12/knobs>; rel="knobs"

Paging - Example

              GET /widgets?limit=100
              Link: </widgets?limit=100&offset=100>; rel="next", 
                    </widgets?limit=100&offset=22300>; rel="last"

              GET /widgets?limit=100
              Link: </widgets?limit=100&marker=id123>; rel="next"


  • Content Negotiation
    Accepts: application/vnd.widgets+json; version="1"
  • URL Based

URL Based

  • Easiest to implement for you
  • Easiest to implement for users (no headers)
  • Most widely used in public APIs

Backwards Compatibility

API Change Types

  • Backwards Compatible
    • Additions only. Never remove or rename.
    • New fields added to model must be optional
  • Backwards Incompatible
    • Renaming or moving API roots or fields
    • Deleting APIs
    • Adding Required Fields
    • Changes to authentication or headers/cookies
    • Changes to behaviour

Versioning Rules

  • API version should be a positive integer. Ex: v1, v2, v3
  • Not every product release needs an API version
  • New version only when backwards incompatible change required
  • It is easiest to add versioning concepts in v1!

Common Data Formats

  • Errors
  • Async Tasks
  • Links

Error Format

            POST /widgets/12
              "code": 9001,
              "message": "Error updating resource",
              "details": "Error updating resource with ID 12 because of bla"

Error Format (Validation)

            POST /widgets/12
              "code": "9001",
              "message": "Validation Error",
              "details": "Validation error with the hostname field"
              "fields": [
                  "name": "hostname",
                  "code": "2001",
                  "message": "Hostname field not specified but is required"


  • Always use SSL
  • Public APIs, use standard SSO like OAuth
  • HTTP Basic Auth, Auth Token in cookies/headers
  • Browser Explorable


  • ETag - Hash/sum in ETag header. If-None-Match
  • Last-Modified - Last-Modified header. If-Modified-Since

Random Thoughts

  • Consolidate APIs under single domain
  • Support GZip encoding
  • Consider an SDK for target developers


  • Github and Stackoverflow good examples
  • Consider generating documentation
  • Inline testing


  • What's Wrong With This API
  • Name some other poor APIs