This document provides tips for documenting an API for the first time. It discusses what APIs are and the basics of REST APIs. It outlines what one needs to know about tools like OpenAPI Spec and Markdown when documenting an API. It also offers advice on determining minimum viable documentation and surviving the first API documentation assignment. Key steps include understanding the API, defining essential documentation, adding code examples, and establishing a review process.

1. Documenting an API
for the 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 Asks the 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 and response 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
• The methods
• 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 you need 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 you need 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 you need 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 do on the job?
You are tasked to document an API.
Now what?

15. 15
You are tasked to document an API. Now what?
What to do on the job?

16. 16
•Panic
You are tasked to document an API. Now what?
What to do on the job?

17. 17
•Panic
•Relax
You are tasked to document an API. Now what?
What to do on the job?

18. 18
• No requirement to 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
How to 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)