Design · Add-on
Design an API as a product
An API is a product for developers. Design it to be easy to understand, consistent, well documented and stable.
About 3-10 daysEvergreenLast reviewed 5 November 2026
Who this applies to
- Skills it builds
- Technical and AI fluencyDesign and user experience
- PM types
- TechnicalPlatform
- Product types
- All
- Starting points
- All
- Ways of working
- All
- Experience
- All
- Size of organisation
- All
Steps, by experience
Beginner (under 1 year)
- Start from the tasks developers need to complete.
- Agree simple, consistent naming and patterns.
- Write the documentation and examples before building.
- Test the design with a few developers.
- Plan how you will change it later without breaking users.
Intermediate (1 to 4 years)
- Design from developer tasks with consistent patterns.
- Document first and test with developers.
- Plan versioning and deprecation.
Experienced (5+ years)
- Set API standards across teams.
- Measure adoption and time to first successful call.
- Manage breaking changes with clear timelines.
Who can do this
Owner: Product manager
Can be delegated to
- Backend Engineer or Architect or Tech Lead: Design the API
- Content Designer: Write documentation and examples
Reviewed by: Architect, Tech Lead
Tool examples
- GitHub
- Review the API specification as a pull request.
- GitLab
- Keep the API specification and docs in the repository.
Definition of done
- Design based on developer tasks
- Documentation written and tested
- Versioning plan agreed
Common pitfalls
- Exposing internal structure
- Documentation as an afterthought
- Breaking changes without warning
If you lead the team
What good looks like: APIs are treated as products: easy to understand, consistent, documented and stable.
Ask your PM
- How long does it take a new developer to make a first successful call?
- How do we handle breaking changes?
Warning signs
- Documentation lags behind the API.
- Breaking changes surprise users.