Api Smells

A brainstorming session about the common failure modes of API design and execution, and about the warning signs to watch out for when designing APIs. There were also recommendations for preventing some common ways to fail, noted below.

Convener

Petre Popescu (@steepyirl)

Attendees

Lorinda Brandon

Notes

We've identified 6ish areas into which API Smells may fall:

• Principle of Least Surprise

  • query string bloat (information in query string that is better suited to URI or request body)
  • lack of consistent representation and naming
  • exposure of internal data model
  • same data represented in multiple places
  • excessive abstraction
  • no dogfooding (didn't try API on self before exposing it to customers)
  • heavy use of documentation (indicates that API is not intuitive)
  • false impression of atomicity of operations
  • false impression of synchronicity
  • protip: when accepting a request that starts an asynchronous process, return 202-Accepted (instead of 200-OK) and include cache headers in the response to return an estimate of when the process might complete
  • hearing "Hmm, interesting way of doing that!" from other developers reviewing the design
  • non-atomic updates (that require multiple requests to fully update the state of one resource)
  • multiple ways/multiple end points to update the same information

• Shinto, or: assuming impermanence

  • API changing faster than the documentation
  • outdated documentation
  • designing for eternity

• Put your Customer First (and know who your customer is)

  • lack of well-defined scope
  • excessive customization for 1st use case

• Metrics

  • poor design for traceability (impossible to determine who is making which requests)
  • protip: track usage of docs to see how customers use them; this could indicate areas that are difficult to understand

• Granularity Balance

  • too granular (but how do we decide the proper level of granularity?)
  • same set of calls invoked repeatedly in the same order
  • huge payloads
  • protip: optionally auto-follow hypermedia links (automatically incorporate result from following those links in response to initial request) in order to provide multiple levels of granularity for the same resource

• Re-Using Existing Solutions

  • a lot of verbs in the URIs

• Other API Smells that could not easily be classified:

  • lack of plan
  • lack of extensibility
  • lack of security
  • following trends blindly
  • protip: redact data based on permissions (sometimes, this will involve a separate subsystem for redacting data that was already retrieved, before returning it to the client)