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?