About API docs(what, why, good cases)

API stakeholders

• internal team
• partners
• public

What is API documenation

• any documents for API users. Generally, for developers.
• Primary resource about API
• Normally, it is served in website, widely accessible place

API documenation should be..

• accurate
• educational
• inspiring to use

Types of API documentations

• Reference and functionality : info about endpoints
• Guides and tutorials : how and why you should api
• Examples and use cases : common problem solving examples

Good examples of API docs

• Stripe(https://stripe.com/docs/api/errors)
• Twilio(https://www.twilio.com/docs/quickstart)

Things to consider for making API docs

• For outer client : Our product is targeting developers directly? If yes, docs is important product
• For inner client : you need someone who will create and maintain this

OpenAPI Initiative

• machine-readable descriptions such as OpenAPI, Swagger, RAML are influenced by OpenAPI initiative
• OpenAPI initiative is created by a consortium and operated by Linux Foundation
• Versions
  • 2 : original Swagger spec
  • 3
• describing..
  • API endpoints
  • request data
  • response fields
  • authentication
  • headers
  • etc
• You can generate OpenAPI document from code

Good API tells..

• What's possible
• ciation of facts

Reference

• https://stoplight.io/api-documentation-guide
• https://www.openapis.org/