The Truth About Describing Strings
How to describe strings in API Documentation
By Robert Delwood, A Lead API Documentation Writer
The only goal of API documentation has to be for “great documentation.” I define that as documentation so clear so it defies misunderstanding. Why would it be anything else? While it sounds like a lofty goal, it’s easily obtainable and within everyone’s reach. It begins by thinking like a developer. API documentation writers have to move away from thinking like a technical writer.
Characteristics
When documenting strings, many writers just think about this as little more as characters within quotes, or as a combined set of characters. The following are two examples commonly documented for strings. In a moment, you’ll see how inadequate these really are.
We’re going to move away from this approach. Strings, like all resources, have characteristics. Those characteristics must be detailed.
Maximum length. The longest, or the greatest number of characters the field can be. If this value is omitted, the count is about four billion. This is often seen as excessive. For comparison, War and Peace is about 2,760,249 characters. It’s also considered a security issue in that hostile actors could take advantage of this. Consider a more realistic limit. A person’s name field might safely be limited to 50 or 80. A developer may be needed to clarify the intended use to determine the maximum length. Others have a natural limit.
· A UUID has to be 36 (as well as its minimum, too), a GUID, 32.
· A two letter US State postal code by definition is two.
· A phone number might be 10, 12, or 17, depending on the format.
Minimum length. The least, or the smallest number of characters the field can be. If the field is required, the Minimum must be at least 1. If the field is optional, the Minimum must be 0. Other minimums apply as needed. A UUID has to be 36. You might even get into odd cases. A phone number may be optional, in that the minimum character count is zero, unless the user enters a phone number, and the minimum becomes ten.
Allow spaces. Confirm that spaces are allowed in the string. A person’s name field would naturally allow spaces. A password or an identifier may not. In those cases, the user needs to be told or have this documented.
Special characters. Specify which, if any, special characters may be included. These are the non-standard alphabetical characters such as #, !, or quotation marks. A password or an identifier may require special characters, so clients need to know this. In addition, there may be a limitation on the special characters, such as only allowing a small subset. For example, a UUID or GUID is only allowed a hyphen.
Allow Unicode. Specify if Unicode, UTF-16, or two-byte characters are allowed. These are typically characters for other languages such as a Chinese, Indian, and Arabic. This allows entering names like पूजा चारदरी. They may also include glyphs or symbol character for Latin-based languages.
OpenAPI has tags for minimum and maximum string length. For the display, Redocly isn’t at its best for this, but it’s the [0 .. 50] notation. For its code, see Example 2 lines 3155 and 3156.
It doesn’t have tags for the others. For those, you’ll need to include them as part of the description tag. I use code like this for an HTML table in lines 3158 to 3162.
Addressing these characteristics shows thinking like a developer in anticipating not only the kinds of strings but also what individual responses could be. This allows anticipating the uncommon, corner, or niche cases. They all have to be handled. Developers would have to write code supporting these cases, of course, but it also means graceful handling of possible error cases. Writers, in turn, get ahead of their clients by letting them know about these through documentation. That’s exactly where we want to be.
Thinking like a developer
The quality of the content is the other issue. It must be as complete and comprehensive as possible to allow clients enough information to have an informed or reasonable idea about the value. This needs to happen within a series of concepts for developers. These concepts aren’t unique to strings. All fields and endpoint descriptions should follow them.
Developers never read; they skim. They’re not interested in reading lots of text. They’re looking for an exact piece of information. They will attempt to find it by skimming or the browser’s built-in search. We had better provide it. Towards that goal, keep paragraphs short, and sentences even shorter. I like having the initial sentence of each field to be blunt and to the point. This field does X… kind of thing. See line 3163 above. No details or no other explanation. If more is needed, add the second most important idea as the second sentence. Use one concept for each paragraph. And so on.
List valid values. Some fields accept a limited and predetermined set of values. These are usually enums. Clients aren’t going to know those values until you tell them. And list all of them. In addition, add a description for each one, no matter how obvious the meaning is to you. It may not be obvious to them.
Show all the items. If the list is categorical, such as the currency codes above, and that may have literally several hundred items, list three to five of the most common or supported ones. There are two references to this already (the list itself and the “three-letter ISO 4217 code”) That will help clients. A link can also be provided to the complete ISO list. Links should always open to a new browser page, too. This makes getting back to the original page easier.
Examples. Examples are the key to documentation. They’re along the lines of A Picture Is Worth A Thousand Words. For example, show:
14155552034
(281) 555–8349
and you recognize it immediately as a phone number.
- 426bf73c-180c-4d4b-bbb0–04f0feccfce9
as a GUID, and
- Bearer e0f50beed49b494f-84d357ccb77afbba
as an authentication token. For a poorly named field such as name, something writer’s can’t always change, having examples such as either Charlie Daniels or cdaniels35, something writers can change, is usually enough. And see how clients don’t have to read the documentation to get what they need? Glancing becomes enough.
This is the kind of recognition you want clients to have for every field. When they reference a field, especially after the first time, it’s more to get the field’s format. So, include them and make them obvious.
Always include the example tag. OpenAPI has an example (and examples) tag. See Example 2, line 3168. This tag should be required and checked for by linters. The value used here is the value that shows up in the right column showing the examples. If the tag is null or omitted, some rendering engine use the data type as the value. That’s not what we want. It doesn’t help anyone.
Always include an example in the description. Even though OpenAPI has an example tag that was just mentioned, this is not what I’m talking about now. Instead, always include an example text within the description tag. See Example 1, and Example 2 line 3167. This may seem redundant and even unnecessary. Afterall, there are examples in the right column, right? Perhaps.
First, there may not be an example next to the field. That would mean clients have to scroll up or down, may be a considerable number of times, only then to get back to their field. This annoys readers. Especially when the workaround is so simple.
Second, the clients are already where they want to be, don’t make the move by scrolling, linking, or some other movement method. Put all the information in one place. This is our one chance to be loved by the clients.
Third, you can include multiple examples. Often the valid value may have more than one format. Consider phone numbers, see the example below. By listing examples, clients know at a glance which ones are allowed.
In contrast, either instance for the postal code allows clients to understand that a five number code is allowed, although the zip_code is explicit with the example. But how about ZIP+5? Is that allowed? The client doesn’t know with this documentation. They will have to try the call once.
The last case makes this clear. The maximum length is 10, and the example shows ZIP+5. There is no doubt now that either postal code format is supported. Remember I defined great documentation as documentation so clear so it defies misunderstanding. We achieved that. For one field. Now, do that for all the other fields.
Parting Comments
Mix it up. Notice that the three zip_code examples (two in the field description and one in the right examples column) are different. Feel free to mix it up and use different examples each time. It gives a greater diversity and versatility to the documentation.
Don’t use patterns. Make the examples as close to realistic as possible. That means, don’t use 123 456 7890 for phone numbers, or Lois Lane for names. Don’t get cute with examples.
Don’t use string for numerics. The most serious offense is using a string for a numeric value. Sage, wise, and experienced developers would never let this happen, but some get through. This is a classic for writers pushing back on developers.
- String conversion is an expensive operation for a server. That means it takes a disproportional amount of time for the server to convert it, preventing other operations during that time.
- More importantly for us, it doesn’t tell clients anything about the field. Clients likely have to strongly type their variables and using a string doesn’t tell them what the type is, such a integer or float. This is a difficult thing to find out for developers, and they don’t like it.
Case sensitive. In the 21st century there should be no reason strings need to be case sensitive. If you see this, immediately push back on the developers. It’s a simple operation for developers to standardize their case within their code. It annoys clients.
Use the format tag. The OpenAPI schema allows for a format tag to be used along with the type tag. Format is optional and is not enforced, meaning any value can be used. But it does give important information to the client. Common formats include time-date, object, url, uuid, and guid. If you know something more about the field, say so. See line 3465.
