API Design Skill

Goal

Design and document API contracts before writing implementation code. API-first development ensures consumers (frontend, mobile, third-party) have stable contracts and implementation details don't leak into the interface.

Steps

1. Clarify the API requirements

   • Who are the consumers? (frontend SPA, mobile app, third-party, internal service)
   • Protocol? (REST, GraphQL, gRPC, AsyncAPI)
   • Auth? (JWT, API key, OAuth2, mTLS)
   • Rate limiting & Quotas?

2. Design the resource model

   # Identify resources (nouns, not verbs)
   Resources:
     - /users            -> User resource
     - /orders           -> Order resource