Successful API Recipe
02 Oct 2021
[
api
design
interface
]
API Lifecycle
- Design
- Mock
- Develop
- Test
- Publish
- Manage
Case 1
- Problem: Product teams often forget who they are dsigning/building the API for.
- Solution: Document a shared understanding of customer needs (and revisti it often!)
Case 2
- Problem: Good design does not necessarily translate to a good product
- Solution: Define customer perceptions and keep tweaking product for better user experience.
Case 3
- Problem: Left hand doesn’t know what the righ one is doing.
- Solution: Document everything!
The Secret Ingredients
Design
- Document API design
- Set baseline metrics (for content)
- Capture product requirement
- Collaborate on terminology
Mock
- Create tutorials
- Design visual content
- Work on Quickstart guides
Develop
- Document techincal design
- User stories and journey maps
- Document user flows/tasks
- Plan and structure content
Test
- Plan onboarding experience
- Improve error messages/responses
- Create user guides, how-tos
Publish
- Publish API reference docs
- Create optional content
- Re-evaluate content metrics
Manage
- Evaluate user feedback
- Fine tune user content
- Enhance support content
Developer Portals
Education
- Onboarding information
- Getting Started
- Authentication
- Authorisation
- Use Cases
Training
- Overview of APIs
- Scenarios
- Workflows
- Tutorials
- References
Communitiy
- Communitiy interaction
- Feedback
- Open-source contributions
Brand and marketing
- Selling API products
- Generating trust
- Pricing
- Evaluation
- Customer showcase
Conclusions
- Good docs elevate decision quality and allow API projects to scale
- Documentation is a powerful tool to unify a project around a common goal, educate teams and users, and make it easy to support your APIs.
- API projects live and die on by how well your customer discover, onboard and integrate your APIs.
- A culture of good documentation practices makes for super successful APIs.
Reference