Technical Writer’s Guide to REST APIs

General 5 Minutes

REST APIs are widely used in web and mobile app development for their simplicity and flexibility in enabling communication between different systems. Documenting REST APIs is an essential practice for developers and technical writers to ensure that users can understand and integrate with the API efficiently. For some reason, however, this tends to come across as more complex than it needs to be. This guide clarifies REST APIs and provides a structured approach for documenting them.

Here’s a breakdown of the content:

What are REST APIs

Let’s start by defining what a REST or RESTful API is. A REST API (Representational State Transfer Application Programming Interface) is a way for different software applications to communicate over the Internet using HTTP methods. Simply put, it connects the client-side software to the backend, such as databases or local or remote file systems. It can also retrieve data from blockchain systems.

Here are some key concepts:

Everything in REST is considered a resource. This can be any kind of object, data, or service the API provides access to. Each resource is identified by a unique URL. This is the location where they can be retrieved.

REST APIs use standard HTTP methods to perform actions on resources. These include the following:

  • GET – Retrieve data from the server. For example, this gets information about a user.
  • POST – Create a new resource. For example, this creates a new user.
  • PUT – Update an existing resource. For example, this updates user details.
  • DELETE – Remove a resource. For example, this deletes a user.
  • PATCH – Partially update an existing resource.

Each request from a client to the server must contain all the information the server needs to fulfill the request. Headers provide metadata about the HTTP message and are crucial for processing requests and responses. Bodies contain the actual data being sent (typically only used with POST, PUT, and PATCH methods), whether it’s input from the client to the server or the server’s response to the client. The server doesn’t store session information, making the interactions stateless.

REST APIs generally return data in a structured format like JSON (JavaScript Object Notation) or XML (Extensible Markup Language).

Each resource is accessed through a unique URI, like https://api.example.com/users/123, where /users/123. This is the endpoint for a specific user.

Documenting REST APIs

Let’s talk about how they can be documented. The following is a structured approach to accomplish this:

  1. Provide an overview of the API.
    • Include the following in your overview:
      • What it does
      • Its purpose
      • Who it’s for
    • Also include the root URL for the API. This is the foundational part of a REST API’s URL. It serves as the starting point for all API requests, with specific endpoints appended to it. For example, https://api.example.com/v1/. It includes:
      • Protocol (https://:) – Usually HTTP or HTTPS (secure).
      • Domain (api.example.com:) – The domain or hostname where the API is hosted.
      • Version or context path (/v1/:) – The version of the API. This is optional and is commonly used to differentiate between versions.
  2. Establish the Authentication Type. This section explains the method used to verify the identity of the API user.
    • Common authentication types include:
      • API Keys – Simple strings that authenticate the client making the request. Typically, an API key is sent as a header or query parameter. Keep the API key private and never expose it in client-side code or publicly accessible locations.
      • OAuth 2.0 – Widely used authorization framework that allows users to grant limited access to their resources without sharing credentials. OAuth tokens typically expire after a set period (for example, 1 hour) and may need to be refreshed using a refresh token. An example of an Authorization Header with Bearer Token looks like this: Authorization: Bearer YOUR_ACCESS_TOKEN
        • Authorization Code Grant – The client gets an authorization code and exchanges it for an access token.
        • Client Credentials Grant – Used by applications, not users, to obtain an access token directly.
      • JWT (JSON Web Tokens) – Compact, URL-safe token format used for transmitting claims between parties. For example: Authorization: Bearer YOUR_JWT_TOKEN. It contains encrypted or base64-encoded information and is commonly used for authentication. JWT consists of three parts: Header, Payload, and Signature. They are separated by dots, forming a token like this: header.payload.signature.
      • Basic Authentication – Uses a base64-encoded string of the user’s credentials in the request header. For example, Authorization: Basic base64(username:password).
  3. Document the API endpoints. This documentation should cover the following:
    • HTTP Method – Specify the method. The methods include GET, POST, PUT, DELETE, and PATCH.
    • Endpoint URL – Include the complete path with parameters (for example, /users/{id}).
      • Parameters –
        • Path Parameters – For example, /users/{id}.
        • Query Parameters – List query strings and their descriptions.
        • Body Parameters – For POST/PUT requests, describe the request body structure.
        • Headers – Any special headers required, such as Content-Type, Authorization.
    • Provide an example of a request in a common format (JSON or XML).
    • Include a list of HTTP status codes your API might return.
      • Success Response – Include an example of a typical success response, along with the expected status code (for example, 200 OK).
      • Error Responses: Document possible error responses (for example, 404 Not Found or 401 Unauthorized) and provide examples of error response bodies.
  4. Explain any limits on the number of API calls, if applicable.
    • Rate Limits – How many calls can be made in a minute, hour, or day.
    • Throttling Response – What happens if users exceed the limit, and how they’ll be notified (for example, 429 Too Many Requests).
  5. Provide details on how errors are handled, including standard error codes and how clients can debug or fix issues.
  6. Mention the current version of the API and how users should specify which version to use (for example, in the URL path or headers). This is an excellent place to explain any deprecation policies or version upgrade plans.
  7. For endpoints that return multiple items, document how pagination works (page, limit, etc.). Explain any sorting or filtering mechanisms, if applicable.
  8. Provide links to any official client libraries or SDKs.
  9. It’s very helpful and strongly encouraged to offer guidance on how users can optimally use the API. Provide best practices for performance, security, and error handling.
  10. Include a changelog that lists new features, fixes, or deprecations in the API over time. This is awesome as it enables developers and users to stay up-to-date with an API’s evolution. It also ensures that changes are well-documented and transparent, which helps maintain stability and improve user experience.

Now, let’s see how this documentation all comes together.

Example of API Endpoint Documentation

GET /users/{id}

Description – Fetch a user by their ID.

HTTP Method – GET

Endpoint – /users/{id}

Path Parameters –

  • id – The ID of the user (required).

Query Parameters – None.

Headers –

  • Authorization: Bearer <token>
  • Content-Type: application/json

Request Example

Response Example

Success Response –

  • Status: 200 OK
  • Body: User object.

Error Responses –

  • 404 Not Found: User with the specified ID was not found.
  • 401 Unauthorized: Invalid or missing token.

This approach ensures that developers can quickly understand how to use the API and integrate it into their applications.

Conclusion

Effective REST API documentation is essential for ensuring smooth integration and user satisfaction. By providing clear, structured information about API endpoints, authentication methods, error handling, and usage examples, you empower developers to quickly understand how to interact with your API. Remember, well-documented APIs reduce support requests, improve developer experience, and contribute to the overall success of your product.

When documenting APIs, always aim for simplicity and clarity. Anticipate the needs of your users, provide best practices, and maintain thorough versioning and change logs to ensure that your API evolves smoothly over time. It’s always encouraged to perform the steps and content you’re documenting to document from experience. By following these guidelines, you’ll create valuable documentation that will make working with your API a seamless experience.

Published

One thought on “Technical Writer’s Guide to REST APIs”

  1. Pingback: Simplest Way to Learn APIs Ever! – Double Yew!

Leave a comment