Take Your API Docs from 406 Not Acceptable to 200 OK
0 likes139 views
The document outlines various types of API documentation, emphasizing the importance of developer experience, discoverability, and the decision-making process between building or buying documentation tools. It categorizes types of documentation into tutorials, how-to guides, explanations, and references, advocating for organizing docs by features rather than types. The text also addresses the integration of documentation with existing developer tools and SEO strategies for better discoverability.
Take Your API Docs from 406 Not Acceptable to 200 OK
- 1. Documenting APIs from 406 Not Acceptable to 200 OK
- 2. Any carrier Any marketplace James Messinger Product Director @James_MessingerJamesMessinger
- 3. Documenting APIs | Agenda ● Types of documentation ● Developer experience ● Discoverability ● Build or Buy?
- 5. Types of Documentation Tutorial ● is learning oriented ● is a lesson ● allows newcomers to get started How-To Guide ● is goal oriented ● is a series of steps ● shows how to solve a problem Explanation ● is understanding oriented ● explains ● provides background and context Reference ● is information oriented ● Is accurate and complete ● describes the machinery Source: https://www.divio.com/blog/documentation
- 6. Types of Documentation | Spectrum Source: https://www.divio.com/blog/documentation How-To Guide Most useful when learning Most useful when coding PracticalStepsGeneralKnowledge problem oriented Reference information oriented Explanation understanding oriented Tutorial learning oriented
- 7. Types of Documentation | Priority ● Table stakes ● Auto-generatable ● Sufficient for internal APIs 1 Reference ● Solutions for common use cases ● Reduces onboarding time ● Hand-written 2 How-To Guide ● Makes your API more approachable ● Long-form ● Hand-written 3 Tutorial & Explanation
- 8. Types of Documentation | Organization Organize your docs by feature or use case, not by type. Give users one place to go, not four. Tutorial ● Feature 1 ● Feature 2 ● Feature 3 How-To ReferenceExplanation Tutorial ● Feature 1 ● Feature 2 ● Feature 3 How-To ReferenceExplanation Tutorial ● Feature 1 ● Feature 2 ● Feature 3 How-To ReferenceExplanationTutorial ● Feature 1 ● Feature 2 ● Feature 3 How-To ReferenceExplanation ● Feature 1 ● Feature 2 ● Feature 3 Tutorial How-To Reference Explanation Tutorial How-To Reference Explanation Tutorial How-To Reference Explanation
- 10. Postman Collection OpenAPI Definition JSON Schemas Run in Postman Button Developer Experience | Beyond Documentation Integrate with the tools developers are already using
- 11. Developer Experience | Native SDKs ● Familiar ● Beginner friendly ● Reduced onboarding time ● Improved productivity ● Keep focus on functionality, not implementation ● Promotes community ● Not just an API client ● Ensure best practices ● The primary method of using your API
- 12. not endpoints & verbs Developer Experience | Native SDKs The primary method of using your API Provide first-class SDK docs Complete code samples Code samples should use SDKs Installation instructions Separate docs for each language IDE & editor screenshots Project templatesClasses & methods
- 14. Discoverability Search engine optimization Increased product awareness Shareability Organic growth Analytics Spot popular topics, trends, flows Your documentation is part of your content strategy
- 15. Discoverability | Metadata WebAPI & APIReference JSON-LD used by more than just Twitter requires a server used by more than just Facebook Twitter cards OpenGraphoEmbed embed cards, content preview Shareable enrich search results with context Customize search engine results
- 16. Discoverability | Page Per Topic popular topics, related topics, flow smaller pages, less memorybookmark individual topics separate embed cards for each topic better user experience + seo Analytics Shareable Faster load times Bookmarkable Mobile optimized separate index entries for each topic Search engine optimization
- 17. Discoverability | Progressive Enhancement pages should be usable while JS loads even if JavaScript fails or errors previews only includes static content crawlers don’t always run JS progressive features are optional Faster load timesSearch engine optimization Mobile optimizedUnfurl friendly Content still loads for loading content or navigation Don’t rely on JavaScript
- 18. Build or Buy? Documenting APIs
- 19. Build or Buy? | Reasons to Buy The API ecosystem is rich with documentation builders and end-to-end API lifecycle tooling
- 20. Faster time to market Focus on core product offering Reduce initial costs No competitive advantage gained Limited budget Already proven solutions Integrations Internal API Feature complete Lack of expertise Build or Buy? | Reasons to Buy
- 21. It’s never been easier to build your own API docs Build or Buy? | Reasons to Build
- 22. Flexibility and control Product differentiator Competitive advantage No vendor lock-in Personalization Increased productivity Nonstandard API Workflow integrationSpecialized requirements Search engine optimization Build or Buy? | Reasons to Build
- 23. ● API as product ● Product differentiator ● Dedicated DX team ● API as feature ● Internal APIs ● Early stage product Build Buy Build or Buy?
- 25. Documenting APIs from 406 Not Acceptable to 200 OK