𝗔𝗣𝗜 𝗗𝗲𝘀𝗶𝗴𝗻 𝗠𝗮𝘀𝘁𝗲𝗿𝘆: 𝗙𝗿𝗼𝗺 𝗘𝗻𝗴𝗶𝗻𝗲𝗲𝗿 𝘁𝗼 𝗔𝗿𝗰𝗵𝗶𝘁𝗲𝗰𝘁

𝗔𝗣𝗜 𝗗𝗲𝘀𝗶𝗴𝗻 𝗠𝗮𝘀𝘁𝗲𝗿𝘆: 𝗙𝗿𝗼𝗺 𝗘𝗻𝗴𝗶𝗻𝗲𝗲𝗿 𝘁𝗼 𝗔𝗿𝗰𝗵𝗶𝘁𝗲𝗰𝘁

An API is a contract. It is a promise to the developers you serve. Broken promises cost money and trust.

Design for the consumer. Do not design for the implementer. Consistent APIs are predictable.

Stop thinking in procedures. Think in resources. Wrong: /getUser Right: /users Use HTTP methods as verbs.

Idempotency is a must for payments. A retry should not charge a customer twice. Use a unique key for each request. Store the result. Return the same result for the same key.

Stability wins. Do not break your users with every update. Add new fields. Keep old fields for a while. Use versioning to evolve your system.

Security starts at the boundary. Treat all incoming data as a threat. Validate everything. Check ownership on every request to stop BOLA.

Scale your performance. Use cursor pagination for large data. Offset pagination slows down as data grows. Set rate limits to prevent abuse. Use ETags to save bandwidth.

Stop writing code first. Write your OpenAPI spec first. This forces you to think about the contract. Move from writing endpoints to designing systems.

Source: https://dev.to/ali_algmass/api-design-mastery-from-engineer-to-architect-2bh