Examining an API Reference Page
[Home] [Writing samples] [LinkedIn]

By Robert Delwood

Lead API Writer

Look at someone else’s pages – they’re easier to critique.

Introduction

Looking at others’ API reference pages should be a requirement for all API documentation writers. I do this, whiling away time at the Programmable Web (https://www.programmableweb.com). Our aspect of technical writing is less a science and more of an art. But that’s not how it’s taught. We are told about rules and strict guidelines in almost right and wrong fashion. And to an extent that’s true, and they’re something we need. But we need to go beyond those after some point. We’re trying to communicate concepts and ideas. It doesn’t matter if they’re in the technical realm. Expressing concepts and ideas doesn’t have a realm. We need to communicate with our readers, and like art, that’s a personal journey.

I am convinced the best API reference page has not yet been written, that the epitome of our craft is yet to be created. Until then, I can look at others’ pages. And we can see a lot. My view is to take the aspects I don’t like and ignore them. Take the aspects I do like and incorporate them. In all cases, improve them and make them yours. The intent is to create a signature for yourself.

This instance may not be that case. The following are comments about an API reference page. The comments are mine alone. This critique is meant only as a positive. For as good as we want our documentation, there will always be one restriction that cannot be overcome: Time. We will never have the time to make our documentation as deep, as complete, or with as many examples, as we would like. There will never be enough writers to keep up with developers. The best we can do is manage these restrictions. Get the important stuff first and maybe come back later to fill in the gaps. So, omissions are expected and we can’t fault ourselves for that.

This documentation is no exception. There are some good examples here worth commenting on. But as they’re being read, also notice there is usually a higher goal being pointed out. Learn the theory, the rest becomes implementation details. For instance, one comment is that every parameter needs an offset one sentence introduction. That sounds like a rule. But the theory is to make information easy to find on the page. The short sentence allows readers to get the gist of parameter quickly. Offsetting it makes it easy to find. Not only in one case, but the reader now has a format to expect to find these summaries all over the page.

The Details

Sample image

This is the request name and page title. There’s a table of contents on this page that isn’t shown here. It lists this request as GET Prepay. However, as a convenience to the reader, I like seeing the complete name as the title. For instance:

GET /Prepay

All the information the reader needs is in one place at one glance. They don’t have to check around the page to confirm this. And if you think about this, why would you do that to them? For instance, what if there were also a PUT or POST version of the request, too? Simply Prepay isn’t going to be obvious enough from this title alone. And while they might be able to look at the table of contents, it’s just more work for the reader. Also, capitalization matters. Some servers are case sensitive, so be careful to document the request name exactly as it appears in the developer’s code.

 

This is the request summary description. They get this right. Have one sentence that stands alone so it’s easy to see, and stated as plainly as possible, describing the request: “This request does X.” If this is not the right request for them, by reading only one sentence, you just saved them time. This is something they will love you for. If it is the right request for them, they will love you for that, too, because it quickly confirms something they want to know. That gives them peace of mind. You can use additional paragraphs, like they did here, to then explain in more detail what this does.

Peace of mind is an overlooked quality but one that immensely pays off. It’s also so rare of a writing trait that it’ll be recognized instantly. Peace of mind is the quality that the reader knows they are doing the right thing, every step along the way. It’s comforting. It confirms actions taken are the right ones, and it confirms what’s going to happen in the next step.

The problem with this description, however, is that I think it’s wrong. “Send Card details.”

First, there’s no reason “card” needs to be initial capitalized.

Second, it’s a GET request meaning we expect to have information returned from the company. While users have to send some amount information for the request, the intent is that the important stuff is what comes back. The second sentence even says that. “This resource returns information…” I think these two sentences are confusing and contradictory.

 

This is the overview. After one sentence summary description, add as much additional information about this request as needed. But this sentence has problems.

First, consistency is going to be a common theme throughout. Here, that’s with their use of periods. All sentences need to end with periods. Almost none of them do. In fact, it appears that the style guide requires not using a final period, and that the first sentence is the wrong use. Style guides can’t do that. They can’t overrule common grammar guidelines.

Second, this is an awkward sentence. Looking at two parts: “the card products eligibility against a promotion” and “corresponding card details if configured[.]” The statement may be technically correct but it doesn’t make sense. For both citations, additional context is required. That’s the purpose of the overview. The “promotion” isn’t mentioned again on this page, and “if configured” is never explained. If you mention an option, you must also mention how to understand that option. That helps the reader. How do tell if it’s already configured? Are different values returned in either case? This is the one page in the API reference guide that will fully explain this request, so these details have to be here. At the least, add a link to how it’s configured. Otherwise, you’re doing them a disservice.

This is also a good example that just being grammatically correct isn’t enough. The sentence combines two concepts with an “and” conjunction. But as mentioned, it’s awkward. Keep in mind this is technical writing. We shouldn’t have to guess what it means. One aspect writers new to API documentation that surprises them is that there can be much more nuance and subtility in messages. We’re trying to condense developer’s lines of code into a sentence or two. That means breaking down concepts into individual ideas. Maybe this might be better handled as two bullet points:

This resource returns:

  • information of the card products eligibility against a promotion,
  • corresponding card details if configured.

Each point may require additional sentences. One hallmark of clarity is succinctness and brevity. Use technical terms consistently and meaningfully but be plain and direct when explaining concepts. Every bit of information you introduce has be made useful. That is, explain the concept. Use examples where a value is found or used. Show how to engage the concept. For instance, this example makes a reference to something (which is a problem because they don’t really explain what the something even is) as “if configured.” Explain that.

 

The parameters and properties are the core of the documentation. I’d suggest to standardize your format and, above all else, be consistent.

Are any of these parameters required? As it’s presented, they all look optional although I suspect the request fails if nothing is provided. Readers need to know which ones are required. If the parameter is optional, what is the default value?

Like for the request itself, the first sentence needs to be short and to the point. “This parameter does X.” This forms the foundation for the rest of its description. The parameter aliasId does this. The parameter isPan doesn’t. It just starts directly into the values, which is disorienting for readers.

Sentences need to read like sentences, not sentence fragments. Add determiners, such as “A Unique ID for a given card…” or “A current Timestamp…”

Never use acronyms. That’s worth repeating: Never use acronyms. No one knows what they mean. For example, of “VCES will return the alias ID…” VCES is never mentioned on the page, and don’t do the reader disservices by assuming they know stuff. They’re not going to. Always spell it out. And just not on first occurrence. The first occurrence approach is so 1980s. Remember, because of Internet searches or links from other places in the documentation, readers can now land directly anywhere on the page, so they may not see first occurrence. The same is true for the reference to PAN. It’s never explained. Actually, it is spelled out. One of the parameters is named permanentAccountNumber. However, it’s never associated with the acronym PAN, and is unreasonable to make the reader connect the two.

All parameters and properties need an example. To their documentation’s credit, they all do have examples. Keep in mind, after readers get familiar with this request, they will be on this page only to reference values. That means they are likely looking exclusively at the examples, such as what the value should look like and its formatting. That also implies that they may be on this page as long as literally a single glance. That’s why it’s important to make sure everything is easy to find. In this case, I’d suggest offsetting all examples as a new paragraph. Otherwise, the example blends into the parameter explanation.

The examples are presented inconsistently. As examples:

  • aliasId has its example within parenthesis “(e6a9f601-6066-40e4-a9b8-823dbf985466)”.
  • correlationId is plain text(asdnsdmbnmfsbg12833247).
  • permanentAccountNumber doesn’t have actual examples, just a textual description about the format (“Payment card number - 16 digit”).
  • isPan includes the notation true/false indicating the complete set of values but no a single example like the others.
  • requestTimeStamp has its example within quotation marks ("03/25/2020 5:26:26 PM").

In other words, for seven request parameters, there are five different formats.

correlationId. The description includes “Should be same for validate, redeem and prepay API for a given card…”

First, these are references to other requests. This might have been more obvious on the actual page because the table of contents would be just to the left. However, in context, make it clearly obvious with something like “Should be same for GET /Validate, GET /Redeem, and GET /Prepay…” Perhaps also add links to those pages.

Second, never use “should.” “Should” in technical documentation is a weak word. Here, it implies that this value doesn’t have to be the same for the others. Something is either required or not, and there are consequences about using it or not. So always be explicit in these cases.

Third, where does this value come from? You need to tell the reader more about correlationId.

isPan. For Boolean parameters, those accepting either true or false, naming the parameter like a question is good. So, to the question isPan, it makes sense for the reader to see true of false. In other words, this is a good name. They could have named it just pan but that just makes the reader guess what the parameter is supposed to do.

This brings up a good point, that of the API documentation writer as a developer experience advocate. Often, writers hold developers in too much esteem. Developers have their own perspective. Writers have their own perspective. The two perspectives are not, and should not, be the same. Writers are working for the client developers and are their spokesman. This includes anything that makes the client developer’s job easier. If a request or concept doesn’t make sense for the client, the writer has an obligation to open a ticket. Here, the writers would be correct to question the use of just pan instead of isPan in the name of good developer experience.

permanentAccountNumber. The issues are similar to isPan. Add a meaningful description. Add examples for both cases mentioned. Notice, though, that there is a reference to isPan. If there is a reference one way, then there needs to be a reference the other way. That is, from isPan to permanentAccountNumber as well. Apparently these two parameters work together. That also means the first case here needs to be the same format as the second case. At the least, it needs to mention that isPan must be set to true. That way nothing gets missed.

requestTimeStamp. This is a confusing parameter.

First, it’s unusual to pass in a timestamp for a request. The user’s not going to know that, and that’s a value best returned by the server, especially if it gets down to the seconds or even microseconds.

Second, it’s called a requestTimeStamp but described as a “Current Timestamp…” The capitalization error aside, those two labels sound like they’re referring to different things.

Third, the time formatting is inconsistent. It’s described as “mm/dd/yyyy hh:mm:ss” but the example is “03/25/2020 5:26:26 PM”, with an AM/PM stamp added. This is a good example about examples. If this parameter only had the textual description, users would probably use the “03/25/2020 5:26:26” format. Include the example, they’d probably then use “03/25/2020 5:26:26 PM”, even that it contradicts the description. Such is the power of examples. This might be a minor case, but the documentation needs to be accurate and consistent.

tokenAccountNumber. Add short description. Add complete example. There are surprising number of “If you are certain” decision statements. More context needs to be added about this, perhaps in the overview. How can a user be certain? What are the consequences of providing an incorrect value?

vendorUniqueId. Add short description. This parameter takes a discreet value. That is, only allowed values from a list of possible ones. Here, one example is BENEFIT_PROD but presumably there are more. In this case, always include the complete list, and an explanation of each choice. This allows the user to select their correct value. The list needs to be included here with the parameter, almost regardless how long that list is. The writer’s requirement is not to have a short page, or to have an easy page to write. The requirement is to have complete information. If the list is excessively long, a link to the complete list can be included. The point is that you’re providing all the information the reader needs.

Responses. The Responses section looks like the writers didn’t even get to them. There’s no point in reviewing these other than you can apply many of the comments above to this section.