## Key design principles  [^fn1] [^fn1]: [(Video) Amazon CTO's 6 key guidelines on designing APIs (re:Invent 2021 keynote)-01:10:46](https://youtu.be/8_Xs8Ik0h1w?t=4246) by [[@Werner Vogels]] 1. [[API]]s are forever 2. Never break backward compatability 3. Work backwards from customer use cases 4. Create APIs with explicit and weel-documented failure modes 5. Create APIs that are self-describing and have a clear, specific purpose 6. Avoid leaked implementation details at all costs ## High-level considerations - Protocol: [[REST API Design|REST]] vs [[GraphQL]] vs other - Authentication & Authorization requirements - What clients will be consuming this API? Include all first party consumers (e.g. admin or end user web apps built in-house) and third parties (customer integrations). - Throughput and latency needs - Multi-tenancy needed? e.g. do different user organisations have separate datasets? Do multiple users within the same organisation need distinct auth? - What are the access patterns that will influence the design of the API? - Is it a simple CRUD API which reads/writes data from a backend database or is there the need for more complex business processes to be initiated? - Is there the need for data to be pushed to clients when certain system events occur? e.g. via webhooks or GraphQL subscriptions? ## See also - [[Writing software design documents]] - [[API documentation]]