api-design-principles

Master REST and GraphQL API design to build intuitive, scalable, and maintainable APIs.

• Design REST and GraphQL APIs using resource-oriented principles
• Use HTTP methods with correct semantics for actions and data retrieval
• Implement versioning strategies for backward compatibility
• Apply schema-first development with strong typing in GraphQL

• Resources are nouns, not verbs (e.g., /users, not /createUser)
• HTTP methods have clear semantics (GET, POST, PUT, PATCH, DELETE)
• Use consistent naming and nesting for resource hierarchies
• Support pagination and filtering in queries and responses
• Return standardized error responses with clear details
• Use HATEOAS to enable self-descriptive, navigable APIs
• Version APIs via URL, header, or query parameters
• Leverage schema-first design for clarity and developer experience

1. 1.Design new APIs using resource-oriented endpoints
2. 2.Refactor existing APIs to follow REST or GraphQL best practices
3. 3.Establish team-wide API design standards
4. 4.Review API specs for correctness and usability
5. 5.Migrate between REST and GraphQL with clear mapping