Documenting at the API Level

👉 Writing Tip #6: Make things real by adding examples

Key points in this video

You don't have to have a "general" section, but it helps to give your users an overview of what to expect.

Some considerations for what to put in your "general" section.

  • Information about the documentation
  • description (capabilities, technical information)
  • pre-usage info (signing up, creating an app)
  • base URL, versioning
  • rate limiting
  • contact information
  • authentication
  • error handling
  • pagination
  • common parameters
  • request/response formats, headers, structure

If you have a lot of content in some of these sections, you should consider creating separate guides.

Some tips when writing general documentation:

  • Avoid information overload. Not all information is helpful, or needs to be presented NOW.
  • Write for your audience. Use terms they'll know, provide links to additional documentation.
  • Don’t be afraid to repeat yourself. For example, you might need to describe the common parameters in the general section and again for each endpoint. A good dose of repetition can aid clarity.
  • Don’t over-generalize. If the information doesn't apply to all or most endpoints, don't put it in the general section.

Some examples we looked at:


Hopefully you’ve set up the API infrastructure for Hazam. Next up: documenting at the API level.

What pieces of general information do you think will be important for Hazam users? Come up with a sample introductory section containing these. You can share your results in the Discussion area.

Complete and Continue