Skill Profile
API Design
"The observable action of defining the contracts, endpoints, data models, and interaction patterns of a software interface in order to make it intuitive, stable, and useful for the developers who will build against it."
YOUR SKILLS
Problems This Skill Solves
- An internal microservice is being integrated by three teams — a well-designed API prevents each team from needing to understand the implementation details
- A public API is being versioned — clear design decisions prevent breaking changes from disrupting external developers
- A mobile app is fetching too much data — API design (field selection, pagination) reduces payload size and improves performance
- Developers using the API are repeatedly making the same errors — improved naming and error responses reduce support burden
"REST is always the right choice for APIs."
REST, GraphQL, gRPC, and event-driven patterns each suit different contexts. The best API design matches the consumer's needs and the team's operational model.
"RESTful API design is mainly about following HTTP conventions — correct verb usage and URL structure produce a usable API."
REST conventions address the surface structure of requests and responses, not the harder design decisions: how to handle partial failures, how to version breaking changes without forcing immediate client migration, how to design pagination that remains consistent as underlying data changes, and what error payloads should contain for clients to recover programmatically. Correct REST semantics do not resolve these.
Research & Outlook
APIs are the foundation of modern software composition. AI code generation is increasing the volume of API consumers, raising the bar for clarity and stability. API design as a discipline is professionalising, with dedicated DX teams and platform engineering roles.
See This Skill In Action
Watch a professional demonstrate API Design in a real working environment — what it looks like, how it's applied, and why it matters.
Technical / Software Engineering
API Design
Also Known As
Growth Path
Can write a basic REST API with sensible HTTP verbs, status codes, and JSON responses. Understands the difference between GET, POST, PUT, PATCH, DELETE.
Designs APIs with consistent naming, pagination, filtering, and error contracts. Writes OpenAPI specs, considers versioning strategy, and documents for external consumers.
Defines API governance standards across an organisation, designs platform APIs used by hundreds of developers, and navigates trade-offs between REST, GraphQL, and gRPC for complex product domains.
How to Practise
- 1.Design a REST API for a simple domain (e.g. a library or todo app) — write the OpenAPI spec before writing any code
- 2.Compare the design decisions of three public APIs (GitHub, Stripe, Twilio) — analyse their naming conventions, error formats, and versioning strategies
- 3.Build a GraphQL schema for a product you use daily — identify where REST and GraphQL make different trade-offs
- 4.Review an existing API you work with and document three changes that would make it easier to consume
How to Prove
- ·OpenAPI specification authored for a production service (link or PR reference)
- ·Public or internal API documentation written and maintained
- ·Evidence of an API versioning strategy you designed and defended in an architecture review
- ·Developer feedback or NPS scores from teams consuming your API