Download to read offline
Documenting an API for the First Time? Quick-Start Tips for Your First API Documentation Assignment
- 1. Documenting an API forthe First Time? Quick-Start Tips for Your First API Documentation Assignment Petko Mikhailov Content Strategist PROS
- 2. REST API BASICS 2 •API definition: A set of rules (interface) that two systems (programs, components, services) agree to follow What are APIs?
- 3. REST API BASICS 3 •API definition: A set of rules (interface) that two systems (programs, components, services) agree to follow. • Web API definition: A set of rules (interface) that the systems (programs, components, services) which communicate with the HTTP(S) protocol agree to follow. • RESTful API definition: A set of rules (interface) that two systems (programs, components, services) which communicate with the HTTP(S) protocol using the REST standard agree to follow. What are APIs?
- 4. REST API DOCS 4 •TC profession keeps up with technology • TC becomes more technical • TC integrates with development • TC is development • Documentation becomes important • TC can bring value • TC can contribute to the whole development cycle • Require “manual” documentation • A stepping stone into programming For Technical Communicators: What does this mean?
- 5. REST OVERVIEW GET Asksthe server to retrieve a resource. POST Asks the server to create (and configure) a new resource. PUT Asks the server to edit/update an existing resource. DELETE Asks the server to delete a resource. 5 The four main REST methods
- 6. REST OVERVIEW Request andresponse structures https://evolution-of- tc.com/ https://evolution-of- tc.com/ 66
- 7. REST API DOCS 7 •Meant to be consumed not by humans but programs • REST is a style, not a standard • Typically explained by devs • New and inconsistent terminology What makes them difficult: Are APIs difficult to learn?
- 8. REST API DOCS 8 •Easier to learn than platform APIs • Only 4 methods • Don’t require knowledge of programming languages • Lots of materials are available What makes them easy: Are APIs difficult to learn?
- 9. REST OVERVIEW 9 • Themethods • The request • The response • The endpoints • Header and body • The parameters • The data format (JSON, XML) • Authentication • How to pass parameters in the request • How to interpret the response The REST technology in use What do you need to know?
- 10. What do youneed to know? 10 • REST • The JSON data format • YAML • Postman • cURL • OpenAPI spec • Swagger (and SwaggerHub) • Stoplight • Git (and GitHub) • Markdown • How to build API reference content out of the spec • What makes a good API documentation Tools and technologies
- 11. 11 Reference content (“API documentation”) •Endpoint descriptions • Error codes descriptions • Glossary Non-reference content (“user guide”) • API overview • Authentication and authorization requirements • Rate limiting and subscription plans • Getting started / quick start guides • Tutorial • Code samples • SDKs and sample apps • Quick reference • Best practices • FAQ What do you need to know? What API documentation consists of
- 12. What do youneed to do? 12 • Begin with some introductory material about REST APIs • Complete an online API documentation course • Review some APIs and their documentation • Try using some APIs as a developer • Start building your portfolio • Become a beta tester • Get comfortable with the docs-as-code concept Getting there
- 13. What do youneed to know? 13 • Documentation source in plain text files • Storing docs in the same repositories as the programming code itself • Collaborating using version control such as git and GitHub • Automating the site build process through static site generator • Versioning docs through git tags/releases Docs-as-code concept
- 14. 14 What to doon the job? You are tasked to document an API. Now what?
- 15. 15 You are taskedto document an API. Now what? What to do on the job?
- 16. 16 •Panic You are taskedto document an API. Now what? What to do on the job?
- 17. 17 •Panic •Relax You are taskedto document an API. Now what? What to do on the job?
- 18. 18 • No requirementto know a programming language • API docs are badly needed • You are more than welcome - devs don't like to write docs • You are likely to start from a very low level (dev-written docs) • It is structured writing • Devs show understanding • Code examples save the day (and they are provided by the devs). • Same as the other types of TW, you need to know the user. But it's more about playing! • General TW skills do matter • It is structured writing • Process is inherently agile Consider that: What to do on the job?
- 19. 19 • Get the“big picture” • Review competitors’ documentation • Start by editing the endpoint and parameter descriptions • Google what you don’t know • Define the minimum viable documentation (MVD) • Work towards creating the MVD • SDK? • Test-use the API yourself. • Provide as many code examples as possible • Ask the “how” and “why” questions • Establish a process for reviewing • Work towards developing the full documentation Surviving your first API documentation assignment What to do on the job?
- 20. 20 Minimum Viable Documentation (MVD) • Schemas •Overview • Authentication • Reference • cURL examples Full documentation The MVD, plus: • Getting Started • Tutorials • SDKs and sample apps • Rate limiting and subscription plans • Quick reference • Best practices • API glossary • FAQ What to do on the job? Determine the deliverables • Schemas • Main use case(s)
- 21. API Docs Wizardy 21 Howto document an API in 10 minutes?
- 22. API Docs Resources 22 •Online courses: • Zapier’s API introduction course • SDK Bridge • API the Docs • Tom Johnson’s course • Learn API Documentation with JSON and XML • API marketplaces: • RapidAPI • ProgrammableWeb • Sample API documentation sets: • MailChimp • MailJet • Mailgun • SendGrid Check out these resources
- 23. API Docs Resources 23 •Books: • Standards and Guidelines for API Documentation • Tools and Platforms • Postman • Swagger • ReadMe • APIgator • Stoplight • Git, GitHub, and GitHub Pages • Jekyll Check out these resources (continued)