Security by design

Security considerations are a critical part of the design of any API. The following principles SHOULD be applied during an service API's design and development:

• Operations SHOULD be simple and narrowly scoped such that they that are easy to reason about, easy to test, and closely match specific authorizations.
• Convenience features SHOULD be carefully weighed against the additional complexity they require, and eschewed where a strong justification is not present.
• Features and data that are not solving a well-understood use case SHOULD NOT be included in a service API.
• Sensitive information SHOULD NOT be returned in more operations and resource contexts than necessary.
• Where feasible, resources SHOULD be designed to be simple, easy to delete and recreate, and with immutable qualities. Large, complex, long-lived resources with large numbers of mutable properties SHOULD be avoided.

These approaches contain the attack surface of an API, and allow for more comprehensive security testing.

Attack vector analysis

When designing and developing a service API, industry resources on common attacks and attack mitigation SHOULD be considered. Recommended resources include:

• OWASP API Security Top 10
• NIST Guide to Secure Web Services
• MITRE attack matrices for SaaS and IaaS

See also

Important best practices with security implications are addressed across this handbook:

• Authentication
• Authorization
• Encryption
• Robustness
• Validation for formats, parameters, and types