The Case Against Automated Code Samples
By Robert Delwood, a Lead API Documentation Writer
Introduction
The layout and visual display of the API documentation is important for the developer experience. It defines how easy or difficult it will be to find information, to read topics, and to copy examples. Yet, it is one of the most overlooked items in the developer experience. Perhaps in parts because layout and design are not a strong suit for API documentation writers, or that many API documentation writers are themselves not developers and so don’t fully understand using their own documentation. However, I think the two most important reasons are:
The documentation is rendered by third-party tools. These include tools such as ReDocly, ReadMe, and Stoplight, or site generation tools like Jekyll or Gatsby. These set the document layout themselves, and writers have little control. Handing control of something this important to someone else is not a good idea.
API documentation writers don’t think big. A sure sign of inexperienced API documentation writers is that they don’t think big. They assume all requests and parameter lists are small or request bodies are simple. For example, that requests have only one or two parameters. In practice, this is far from the case. As products get more complex, requests get more complex. API documentation must accommodate all cases. You will need one model to handle all of these. And that means the model must scale.
Foreign Code Generator Feature
One common layout element rendering tool included is the foreign code generator feature. This is a screen area, usually in the top right corner, that displays calling the request in different languages, such as cURL, C#, or Python. It’s often, too, associated with the Try It feature. The Try It feature in theory allows clients to literally try the request, calling it directly from the documentation, rather than using another application such as Postman.
At first glance, both features seem useful. However, thinking about this, they may be doing nothing more than taking up valuable screen space and annoying clients. Take the case of the foreign code generator feature.
As mentioned earlier, this is a feature that generates code samples. Clients select the language, such as cURL, .NET, or Python, and it creates the code. They copy and paste that into their compiler, and change the variables to their own values. Better versions automatically fill in the variables. It’s presented as a convenience operation. Who wouldn’t like to copy and paste working code samples?
The answer lies in understanding how clients use this code to write applications. Their application is going to make multiple calls to your server, using your API suite. Indeed, that’s the very point of using your API suite. As an example, for an order tracking application, this includes creating access tokens, signing in, getting an order list, getting details on a specific order, canceling an order, and so on. Each action requires a request. These are the same requests displayed by the code generator feature. I think the designer intends that clients can copy and paste the code to be able to move on. But clients aren’t going to copy and paste that code each time. Instead, they’re going to make a function that includes that code. By making it a function, all they must do is pass in the custom parameters each time. That’s a fundamental principle of development: You don’t want to duplicate code. It means that they’re only going to copy that code only once per project. Even less, perhaps, by making it part of a library file and sharing it among projects. They may not even use that code. Each language has several ways to make requests and the displayed code may not be the way they want to do it. With that in mind, the question becomes does it make sense to include it? It may not be for the following reasons.
Takes up valuable screen space. Understanding that this feature will be used at most once, if at all, the code generator feature is now taking up valuable space. Good page design dictates that the most important material is displayed above the fold. Put it right on top of the page. In other words, don’t make the client have to scroll down. However, no rendering engines I know allow this feature to be moved to another location, it may be toggled to be visible or not. Therefore, consider not using this feature at all. This doesn’t mean clients have to go without it. The feature has value. There are alternatives, such as Postman.
Postman. Postman is an API creation and testing application. It is widely used, popular, and is an industry standard. So much so, that we can assume developers already have it loaded. It has two features of interest here.
· It can generate code samples in different languages. That, and it’s a better version than any rendering tool available.
· It’s a testing application. It can make requests. It’s probably the best testing application on the market. It is simple, versatile, and samples can be saved. They can be grouped into collections allowing clients to have ready access to a series of requests and parameters set by us, so they don’t have to.
That makes Postman a more versatile application for both code generation and testing requests.
Don’t advocate languages. The foreign code generator feature presents code in multiple languages. Far from being a good thing, it’s a distraction. This is a professional opinion of mine: API documentation should not advocate the use of a language. It’s up to clients to decide their language and implementation. They can do that better and more efficiently than we can. REST was designed to be language agnostic. We are just to describe the calling requirements and bodies, and let them decide how to use it.
The request body may just be complex. Many writers think only in simple cases. That is, that requests either have no parameters or one or two simple ones. In fact, this is a sign of an inexperienced API documentation writer. In practice, requests, such as POST and PUT, can be complex. They have long, involved, and complicated request bodies. Product order requests, for example, can have 50 or more parameters, including conditional parameters. For instance, they may have geolocation (latitude and longitude coordinates) required but only exclusively if a physical address is not included, product lists, payment information, and so on. Given the sheer number of combinations or amount of information required, the code example may become unusably long or unreasonably complicated.
It’s not how they test requests. Ultimately, the generated code samples are not how clients test requests. Many think that requests are run once and that that would be good enough. It’s not. Again, they’re thinking only about extremely simple cases. Typically, requests must be run multiple times. Different sets of parameters must be tried, and values must change. This makes the generated code inconvenient to use if clients must copy it each time. They won’t. Clients are going to use Postman.
cURL
A special note needs to be made for cURL. cURL (known as Client URL) is a command line tool and library for making HTTP requests, which include REST. It’s built into Windows and Unix. It’s a convenient developer tool because it can do more than just make requests. There’s an appeal in that an entire request can be made in a single, self-contained command, and can be copied and pasted. Many see this as convenient and it becomes a replacement for more robust testing tools. It should not be. I agree that there’s an upfront convenience, which is often the only aspect writers see. cURL commands are easy to include in documentation and easy for clients to copy and paste. It’s in using the request that clients get stuck. It can be difficult to change values, to run multiple times, or, if they see that this is the correct request and values for them, to translate into a REST format. This is an aspect many writers don’t see. We’re now causing work. In short, we document our clients into a corner.
Conclusion
Great documentation requires critically examining all elements. The page layout of the reference guide is usually overlooked. Yet, in a real way, it’s the most important aspect. It’s the contact we have with clients, and its clients will judge us on how easy it is to use. But it’s not complex. What is the single most important piece of information on the page? Put it right on top. What is the second most important piece of information? Put it under the most important one, and so on. Similarly, are all the elements supporting their weight? I made a case here that the foreign code generator feature does not. It takes up valuable space, it may be used at most once, and may even not be relevant to clients. If that is your conclusion, too, consider not using it and put that space to better use.