𝗗𝗲𝘀𝗶𝗴𝗻𝗶𝗻𝗴 𝗔𝗣𝗜𝘀 𝗗𝗲𝘃𝗲𝗹𝗼𝗽𝗲𝗿𝘀 𝗟𝗼𝘃𝗲

𝗗𝗲𝘀𝗶𝗴𝗻𝗶𝗻𝗴 𝗔𝗣𝗜𝘀 𝗗𝗲𝘃𝗲𝗹𝗼𝗽𝗲𝗿𝘀 𝗟𝗼𝘃𝗲

Great APIs feel obvious. You should not guess endpoints. Request formats should make sense. Errors should tell you what to fix.

Start with the user experience. Draft your API before writing code. Ask what endpoints make sense. Ask what responses look like.

Follow these rules:

• Use consistent names.
• Use plural nouns for resources.
• Use camelCase for bodies.
• Stick to one style.

Build for the future:

• Start with /v1/ in the URL.
• Add fields instead of changing them.
• Give notice before removing fields.
• Avoid breaking changes.

Fix your error messages:

• Use structured errors.
• Include a machine code.
• Include a human message.
• Point to the bad field.

Improve documentation:

• Write docs before you ship.
• Explain the mental model.
• Explain the why, not the what.
• Use OpenAPI standards.

Add these features:

• Provide client libraries.
• Use cursor-based pagination.
• Include rate limit headers.
• Offer a sandbox environment.

Avoid the biggest mistake. Do not design for your database. Do not design for your server. Design for the user mental model.

Source: https://dev.to/therizwansaleem/how-to-design-apis-that-developers-love-to-use-4ae5