REST in Pieces? Documenting REST APIs

Like me, you might be a technical writer or an information developer who is writing application programming interface (API) documentation, or maybe you have never heard of it and want to know more. In this post, I want to look at what an API is and what a REST API is. Then I will consider some of the challenges in documenting REST APIs. Finally, I will look at the future of REST and GraphQL.

What Is an API?

An API is like a window that allows an application to share data and processes with other applications. These have become very important in the modern IT landscape where applications based in public and private clouds, accessed via mobile and IoT devices are an everyday expectation.

For example, imagine a popular taxi app. The map rendered there is not usually created by the taxi app. Instead, it uses a map API to access a map service. This service can just send data back to the taxi app or it can send a UI that is rendered within the taxi app’s UI. To configure this, the app developer uses the map developer’s API to access the map data.

What Is REST?

Getting disparate components, applications, operating systems, and middleware to share data and processes with each other has been a long-running challenge in computing and computer networking. Before the internet and the invention of standard protocols by the W3C, applications tended to be siloed in their respective stacks or operating systems. Bridging these gaps was complex and was usually achieved by complex, custom software. This was expensive and difficult to scale and upgrade.

Luckily, the World Wide Web Consortium (W3C) foresaw this issue and set about creating the REST protocol to solve it. REpresentational State Transfer (REST) APIs are APIs that use a common protocol to allow RESTful applications to talk to each other. REST was invented by Roy Fielding during his time with the W3C. In the time before REST, the main API methodology was Simple Object Access Protocol (SOAP) and this was not very simple. In 2000, Roy foresaw a need for a common architecture in the early days of the web:

“Throughout the HTTP standardization process, I was called on to defend the design choices of the Web. That is an extremely difficult thing to do within a process that accepts proposals from anyone on a topic that was rapidly becoming the center of an entire industry. I had comments from well over 500 developers, many of whom were distinguished engineers with decades of experience, and I had to explain everything from the most abstract notions of Web interaction to the finest details of HTTP syntax. That process honed my model down to a core set of principles, properties, and constraints that are now called REST.”

Thus, REST became the standard that Roy envisaged in the intervening 20 years. It served its purpose admirably, allowing disparate nodes to connect and share information and code in a universally understood structure and method.

But what is REST? REST is best understood as a protocol, a common set of rules or language that applications can use to talk to each other. As stated, it was invented to provide this function in the common language of HTTP protocols. REST is a common set of components that can share tasks and data via HTTP protocols in a network (or across the internet).

End-user Versus Developer Views

For us as technical writers, the majority of our audience are developers. These people have a different perspective on APIs from end users. Writers need to appreciate how end users’ and developers’ perspectives of APIs differ. End users tend to never see the API itself; they just get the results seamlessly integrated into their application. Figure 1 illustrates this with the taxi app example.

Developers tend to create APIs, such as the REST API, to allow applications and users of applications to perform actions in the connected application. For example, consider a developer who is creating requests for a REST API. He uses an extension or application (Postman in this case) to create, read, update, or delete objects in the connected database. Figure 2 illustrates this.

Every REST API consists of the following components:

• Resources: A resource can represent anything. Mostly these represent real-world objects or people (or at least they represent the software objects that represent these). In practical terms these are things like a user record or an entry in a database, or whatever the REST API developer wants it to be.
• Endpoints: Endpoints are logical collections of resources that are represented by a unique URL. Again, these tend to represent logical groupings. For example, all employee records might be represented in one endpoint and all customer records might be another endpoint. The endpoint is usually represented as something like /api/employees or /api/customers in the endpoint URL. The developer uses this URL and the required method to perform create, repeat, update, and delete (CRUD) actions.
• Methods: In REST, there are several standard methods like GET, POST, etc. Each of these performs a different technical function. For example, developers might use a GET method to retrieve information from an endpoint, for example a list of employee records. They might use a POST method to send information from their application to the web server (via a calendar API), for example, to schedule an appointment and add it to your calendar. Sometimes API developers may use a POST method to get information, or they may not use POST methods at all and instead use GET methods. Therefore, the technical differences between these methods do not really matter outside of what they represent in a specific API.
• Responses: These resources consist of fields that can be updated and are usually returned as responses. You can request to view these or you can create, edit, or delete the contents of these response fields.

Figure 3 shows the UI of the Postman application. This gives you an idea of what a developer might see when they work with a REST API.

Developers enter the URL and select a method from the Type field. In the Body section, you can see the information that is returned in the response.

However, to be able to fully understand how developers use the REST API, you need to see it or experience it for yourself. You can watch one of the many helpful videos available.

Understanding REST With a Test API

Of course, it is also much easier to understand what a REST API is if you use one. Like a video, this can help with visualizing what you are writing about. Len Baker (my colleague at TWi) and I are currently creating a training course about APIs and REST. As part of this, he created a test REST API that we could offer to participants to help them understand the concepts.

The model is very simple. Users use an application called Postman to create, read, update, and delete customer and employee records from the connected SQL database. This is illustrated by Figure 4. We feel that this is the best way for authors to grasp the concepts of REST and to help appreciate what their readers (REST API developers) want in their documentation.

Documenting REST APIs

What does all this mean for documentation? As you’ve probably intimated by now, REST APIs are very structured in their design and this presents opportunities and challenges for writers. As a writer, you know that your REST API will consist of the main components, that is, resources, endpoints, methods, and resources. However, you do not know how your developer has implemented this until you engage with them and their API.

You also know that your audience is familiar with the concepts. You can reasonably expect that they will understand what the components are. They will know they have to use methods and will expect to use responses. However, like the writer, they will not know the specifics of the implementation that you are documenting.

From an information architecture point of view, you need to decide if it makes sense to group topics by expected business activities or if you should create more technical documentation that maps the model. This is something that authors tend to spend some time thinking about. There can be varying reasons to use one approach or the other:

• Tech-centric model: For example, if the API is very technical and does not map easily to real-world tasks, you might want to consider documentation that more closely follows the model to help users to find reference material more easily.
• Business-centric model: Conversely, your users may only want to know how to perform practical tasks like creating a record or accessing map data. In this case, it might make sense to make your documentation more business-orientated.

In general, we strive to match the business use case as much as possible while also creating a complete technical reference. To do this, we try to use a hybrid of both models that gives the best of both worlds. You can view this in our example documentation.

In this documentation, we want to make it easy for users to get relevant information like a short description of what the operation is used for and what the request URL is. This is shown in Figure 5.

In Figure 6 you can see the request body information with a pop-out example. This makes it easy for developers to see what is and is not allowed for this request.

It is also important to consider the usual topics, like configuration information and connection and security information, that are needed to access the API in a real-world IT landscape.

REST in Pieces?

You may have heard rumours from the front that REST is not long for this world. GraphQL is the new kid in town and word is that it is better than REST. Some say it is so good, in fact, that it will not require any documentation. We think that this might be somewhat overstating the reality.

REST is an architectural protocol but GraphQL is a query language. GraphQL allows developers to query for and return only the information that they need. REST returns its data in specific formats in the responses, and it returns all the data that is contained in that response. In a large IT landscape, this can have some performance implications. It is my belief and the belief of others that IT ecosystems will use a mix of both for some time to come.

What if I am wrong? You might have heard that GraphQL is self-documenting. This is also overstated, I feel. It is self-documenting in the sense that you can associate documentation with objects in the model. Rest assured, I think it will still be up to technical writers to add the context and business knowledge that users will need to use it.

Many thanks are due to my colleague Len Baker for building the test API mentioned here.

 

Images Used

• Image by Christopher Gower, licensed by Unsplash