Remote API checklist
·
263 words
·
2 minute read
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?