{"id":2736,"date":"2023-11-22T11:16:22","date_gmt":"2023-11-22T11:16:22","guid":{"rendered":"https:\/\/www.infobip.com\/developers\/?p=2736"},"modified":"2023-11-22T11:21:12","modified_gmt":"2023-11-22T11:21:12","slug":"the-must-have-content-to-include-in-your-api","status":"publish","type":"post","link":"https:\/\/www.infobip.com\/developers\/blog\/the-must-have-content-to-include-in-your-api","title":{"rendered":"The must-have content to include in your API\u00a0documentation"},"content":{"rendered":"\n

I keep hearing the phrase that API reference is the face of the API. And I wholeheartedly agree with it. However, even though a lot of companies do share this point of view, there\u2019s still not enough done for the API reference in terms of content as opposed to the API design itself and its UI representation. <\/p>\n\n\n\n

Content-centric API reviews are still not a thing, and I think it\u2019s time to change that. <\/p>\n\n\n\n

This blog post lists the API content must-haves<\/em> so that you make sure your API reference provides the best possible developer experience for your users. <\/p>\n\n\n\n

API reference content must-haves <\/h2>\n\n\n\n

There are some aspects of the API reference without which a developer reading documentation gets lost immediately. And to make things worse, without testing the API, they won\u2019t know the correct answer, unless it\u2019s documented.  <\/p>\n\n\n\n

It is then crucial to make sure we can answer as many potential questions with our content as possible. <\/p>\n\n\n\n

Do all fields include a description? <\/h3>\n\n\n\n

All fields you list in the API should have a description. No matter how much you think your field name is self-explanatory, it important that the description verifies that assumption. <\/p>\n\n\n\n

Oftentimes, adding information on what you can use a field for or where would this data be displayed adds a lot of value to the API user, even if the field\u2019s name already provides you with enough information to make a valid request.  <\/p>\n\n\n\n

\"Stripe
Stripe API reference<\/em><\/a> provides context to their seemingly self-explanatory fields, such as email, description, or metadata.<\/em><\/figcaption><\/figure>\n\n\n\n

Is this field required?\u00a0<\/h3>\n\n\n\n

Each field documented in the API reference should indicate whether it\u2019s mandatory. Without it, a developer using the API is subjected to a guessing game right at the beginning of their user journey when they\u2019re constructing their API request. <\/p>\n\n\n\n

It is frustrating and can very quickly lead to the abandonment of the project in search for a similar but better documented API. It is especially important if your API includes a lot of nested parameters which then can prove extremely time consuming to test which combination of parameters will get accepted as a valid request. <\/p>\n\n\n\n

What type is this field?\u00a0<\/h3>\n\n\n\n

It\u2019s tremendously helpful to know the field type while working with APIs. And yes, I know, you can check this in a request sample, but what if you have added your field in the latest release and forgot to update your sample, or what if your request schema is gigantic and doesn\u2019t really list all the fields. <\/p>\n\n\n\n

To remove all unnecessary guesswork for your audience and additional work like executing typeOff(), add the field type to your schema. It\u2019s quite fast for you to document (so, low hanging fruit here) and can be a valuable source of information for developers who use your API.  <\/p>\n\n\n\n

\"\"
GitHub API reference<\/em><\/a> flags their required fields and displays the field type<\/em>.<\/figcaption><\/figure>\n\n\n\n

How to represent a variable?<\/h3>\n\n\n\n

If you have a big product stack and a lot of APIs, be consistent and land on one way to represent your variables. It doesn\u2019t really matter if you use {} or :, it is important that you do it consistently across all APIs so that your user, once they read one API, can immediately start working with the next one, because all content patterns already feel familiar to them. <\/p>\n\n\n\n

Inconsistency, even a small one like this, confuses the brain. It hates incomplete information because it means that it will have to do some heavy lifting itself and lose valuable energy filling in the gaps in the process. <\/p>\n\n\n\n

\"\"
Heroku API reference<\/em><\/a> represents their variables with {} and uses underscores for their names<\/em>.<\/figcaption><\/figure>\n\n\n\n

How to represent deprecated endpoints\/fields?\u00a0<\/h3>\n\n\n\n

It\u2019s a natural process to have endpoints deprecated and end their life cycle and support. But doing so without a proper documentation can have a potentially disastrous effects to companies that depend on that particular endpoint. <\/p>\n\n\n\n

It is then crucial that we communicate endpoint deprecation in a manner that provides as much necessary information for the API users as possible: <\/p>\n\n\n\n