Skip to content
Kitbay
Skill

api-design-principles

MITUpdated on Nov 9, 202642,406GitHub stars

A skill from Seth Hobson's agents collection, in its backend-development plugin, with principles for designing REST and GraphQL APIs and for reviewing API specifications or setting team standards.

What the skill teaches

A skill from Seth Hobson's agents collection, in its backend-development plugin, with principles for designing REST and GraphQL APIs and for reviewing API specifications or setting team standards. For REST it covers resource-oriented URLs, HTTP method meaning, which methods are safe or idempotent, status codes and statelessness. For GraphQL it covers schema-first design, queries, mutations and subscriptions, cursor pagination in the Relay style and structured errors in mutation results. It compares three ways of versioning, and adds rate limiting, OpenAPI documentation, batching loaders to avoid repeated queries, deprecation and query complexity limits. Common mistakes include breaking changes, inconsistent errors and tying the API to the database schema.

Capabilities

  • Design resource-oriented REST endpoints
  • Design GraphQL schemas with cursor pagination
  • Choose an API versioning strategy
  • Review an API specification for common mistakes