API Documentation Best Practices Course
Introduction
- Instructor: Jason Harmon (CTO of Stoplight)
- Course Duration: 90 minutes
- Content Overview:
- Writing good API documentation
- Techniques and tools for creating documentation
- Business impact of good documentation
Instructor Background
- Jason Harmon: CTO at Stoplight
- 20+ years of experience in technology and API
- Roles: Engineering, product, security, IT
- Previous companies: PayPal, Expedia Group, Typeform
- Host of podcast "API Intersection"
Course Agenda
- Introduction to API documentation
- Defining API documentation
- Business impact
- Techniques and tools
- Best practices
API Documentation Overview
- Documentation: A human-readable description for developers.
- Primary goal: Enable machine-to-machine communication.
- Applicability: Relevant to many areas, especially in today's interprocess communication.
Types of Documentation
- Product Documentation:
- Point-and-click experience showing how to use a product.
- API Documentation:
- Developer-centric: Shows how to write code to use an API.
Target Audience
- Developers
- Business and technology leaders
- Internal teams
- External partners
- Things to consider: Authorization, access control, proprietary information, and branding.
Key Documentation Components
- API Reference: Encyclopedia of API usage.
- Concepts and Tasks:
- Explain the job or task the API helps accomplish.
- Examples:
- Example: PagerDuty's API has information in request and response headers, parameters, error handling.
- Concept Example: Detailed, comprehensive description of API concepts.
- Getting Started:
- Guide for new users on how to make their first API call.
Examples of Good API Documentation
- Stripe: Simple steps to obtain API keys, consistent auth method.
- Twilio: Language-specific code examples, interactive “Try it” features.
Writing Good Documentation
- Focus on the audience (internal vs. external).
- Necessary details: Required/optional data, paths, methods, request/response formats, error handling.
- Ensuring discoverability: Use portals or centralized resources.
- Validate accuracy: Internal review and testing.
Documenting API Errors
- Comprehensive description of possible errors.
- Standardize error responses to facilitate better error handling.
- Include application-specific error codes, not just HTTP status codes.
Techniques and Tools
- Spec-based approach:
- Use APIs such as Swagger (OpenAPI) for structured API documentation.
- Code Annotations:
- Embed documentation within code. Ensures synchronization but requires developer involvement.
- Hand-Curated:
- Custom documentation. Easier but hard to maintain accuracy.
Best Practices
- Address broad audiences: Avoid jargon and internal acronyms.
- Clear variable names and function names.
- Practical guides and multimedia elements: Videos, pictures, flowcharts.
- Automated approaches: Use spec formats and tools for syncing.
- Maintain accessibility standards.
- Regularly update content to ensure relevance.
- Simplify content: Avoid unnecessary repetition and bloat.
- Incorporate search optimization.
- Develop a style guide and consistent documentation process.
Benefits of Good Documentation
- Enhances security: Reveals and addresses potential issues early.
- Reduces duplicated effort and promotes reusability.
- Supports customer and developer success.
- Encourages strong adoption and brand affinity.
- Better developer experiences lead to positive word-of-mouth.
Conclusion
- Good documentation is critical for business success and security.
- Building and maintaining it requires thoughtful planning and implementation.
Additional Resources
- Free courses and certifications available at Appek University.
- Monthly webinars with API experts.
End of Course: Complete quizzes for a badge and certificate at appc.university.com.