An API should

  • Be aligned with the business vision and roadmap
  • Adopt a client-first approach for developers
    • See Amundsen Maturity Model
  • Be easy to discover
  • Be well documented
    • API documentation
      • Use of HTTP status codes
      • Schemas for payloads
      • Sample payloads
    • Capability documentation
      • Performance indications
      • Rate limits (soft, hard) and resets
      • Payload limits
    • Warn at sensitive endpoints, payloads (PII, PHI, PFI, etc)
  • Be easy to learn (UX, Simplicity)
  • Be easy to consume (Simplicity)
  • Provide end-user utilisation reporting
  • Provide webhooks for custom actions
    • Actions for utilisation and billing limits
    • Actions for policy violations
  • Scale to meet demand
  • Allow per-customer setting of HTTP headers
    • Support X-HTTP-METHOD-Override for misconfigured proxies
    • CORS for web clients
  • Set caching headers
  • Usability
    • Be versioned
    • Be stateless
      • Provide useful functionality per call to minimise round-trips
      • See Amundsen Maturity Model
    • Be consistent (naming conventions, parameters, errors)
    • Provide clear error messages
    • Support modification timestamps
    • Support unique external identifiers
    • Support pagination, with total set size
    • Support filtering on multiple properties/types
    • Support bi-directonal sorting on multiple ordered properties
  • Be secure
    • Use HTTPS
    • Use access tokens
    • Use whitelisting/blacklisting
    • Federate to external (customer selected) IDP (e.g. Auth0)
    • Provide relevant ISO and SOC reports
  • Allow for domain aliases or custom domains
    • Allow for custom SSL certificates
  • Be supported
    • Multiple levels (with clear prices)
    • Multiple channels
  • Be available in geographic proximity

Questions to consider

  • What business goals does the API drive?
    • Which business functions does it expose?
    • How are business goals tracked and reported?
  • How is the API funded?
  • How is the API positioned?
  • What are the terms of use?
  • How does misuse expose the business to risk?