API Documentation Tools: Using Hoppscotch for API Documentation

#documentation #api #devrel #beginners

Before starting as a Documentation Engineer, I didn't know much about API documentation. The take-home task the company gave me was to document the endpoints of an API given to me. I took this journey and began learning about API documentation and the different tools for documenting API.
I will be sharing all that I have learned so far.

In this series, I have talked about Using Postman for API documentation. This article will look at using Hoppscotch for API documentation.

APIs are central to most modern applications, and providing clear, detailed documentation is essential for developers to understand, interact, and build with them efficiently. Hoppscotch, a web-based API development tool, has rapidly gained popularity for its ease of use and powerful features. It serves not only as a versatile API testing tool but also as a robust option for documenting APIs in a way that is accessible and user-friendly.

Introduction to Hoppscotch
Features That Make Hoppscotch Ideal for API Documentation
How to Document APIs with Hoppscotch
Best Practices for Using Hoppscotch for API Documentation
Advantages of Hoppscotch for API Documentation
Conclusion

Introduction to Hoppscotch

Hoppscotch is a lightweight, open-source API development tool created to make API testing and exploration more efficient. Originally launched as a tool called Postwoman, it was rebranded to Hoppscotch and has continued to evolve, incorporating advanced features while maintaining an accessible, browser-based interface.

Built for developers, by developers, Hoppscotch’s core aim is to simplify the workflow for testing and documenting RESTful APIs. It provides a smooth, user-friendly interface where users can send requests, receive responses, and store information in an organized manner, making it an ideal tool for both API testing and documentation.

Features That Make Hoppscotch Ideal for API Documentation

Interactive API Testing

Hoppscotch enables users to send requests and view responses in real time, making it easier to document API behavior as you interact with it. This feature is especially helpful when documenting response formats, status codes, and error handling.
Collections and Folders

Hoppscotch allows users to organize requests into collections and folders, which can be structured to mirror the API’s endpoints and functionalities. Collections act as a documentation repository, categorizing related API requests and making it easy to reference or share them.
Environment Variables

With environment variables, users can set and manage values like API keys, tokens, and URLs in one place. This feature reduces redundancy and keeps the documentation clean, as sensitive or changeable data can be centralized and updated as needed.
Real-time Collaboration

Hoppscotch includes real-time collaboration, enabling team members to simultaneously work on and review documentation. This feature ensures consistency and allows for instant feedback, a crucial component in creating accurate and up-to-date documentation.
Import and Export Options

Hoppscotch supports importing and exporting collections, which means users can easily share documentation or back up their work. Supported formats include Postman collections, which is ideal for teams migrating from or co-using Postman for documentation.

How to Document APIs with Hoppscotch

Documenting APIs in Hoppscotch is straightforward, and it allows you to organize, describe, and share API details effectively.

Step 1: Create a Collection

Collections in Hoppscotch serve as a central place to group related API requests, making it easy to organize endpoints.

Navigate to Collections: On the right sidebar, click on Collections.
Create a New Collection: Click the + New button, name your collection, and add a brief description. This could be the name of your API or a logical grouping, like “User Management API.”
Save the Collection: After setting up, save the collection to start adding requests.

Step 2: Add and Document Requests

Each endpoint you document is added as a request in Hoppscotch. Here’s how to add and document an individual request:

Create a New Request:
- Inside your collection, click + Add Request.
- Name the request (e.g., “Get User Details”) and specify the HTTP method (GET, POST, PUT, etc.).
- Enter the URL for the endpoint, for example, https://jsonplaceholder.typicode.com/users.
Set Up Request Details:
- Parameters: Add any query parameters in the “Params” tab, like filtering options (?userId=1).
- Headers: Enter any necessary headers, such as Authorization for authentication.
- Body: If the request method is POST, PUT, or PATCH, add the request body content in JSON or the required format.
Add Descriptions and Notes:
- Request Description: Write a brief description of what this endpoint does. For example, “Retrieves details of all users in the system.”
- Parameter Descriptions: For each parameter, specify its purpose and valid values, such as “userId - The ID of the user (integer). Optional.”
- Response Description: Describe the expected response, detailing the main fields returned, status codes, and error messages. For instance:
  - Success (200): Returns a JSON array of user details with id, name, and email.
  - Error (404): Returns a "Not Found" message if the user ID doesn’t exist.

Step 3: Use Environment Variables for Reusability

Environment variables make your documentation adaptable across different environments (e.g., development, staging, and production). Here’s how to set them up:

Go to Environments: On the left sidebar, find the Environments option.
Create a New Environment: Set up environment variables like baseURL, API_KEY, or any commonly reused data.
Use Variables in Requests: Instead of hardcoding URLs and sensitive information, replace them with variables, such as {{baseURL}}/users. This makes your documentation dynamic and cleaner.

Step 4: Test and Record Responses

One of Hoppscotch’s strengths is its ability to send requests and instantly display responses, which helps verify your documentation.

Send the Request: Click Send to view the response.
Document Responses: In the response section:
- Add notes about the structure of the response.
- Describe each field (e.g., id - unique identifier, title - title of the post).
- Note any error messages or unusual cases.
Save the Response Example: For better clarity, you can save a sample response or copy and paste it into the request’s description.

Step 5: Organize and Share Documentation

Organize Endpoints by Folders: Group related requests in folders within your collection. For example, all user-related endpoints can go into a “User” folder.
Export or Share Documentation:
- To share the documented API, export your collection by clicking the Export button and choosing a format like JSON.
- Hoppscotch also supports sharing collections by generating a shareable link that team members can use to view or import the documentation.

Example of a Documented API Request in Hoppscotch

Suppose you're documenting a GET request to fetch a user’s profile:

Name: Get User Profile
Method: GET
URL: https://jsonplaceholder.typicode.com/users/1
Description: Retrieves the profile of a user based on their ID.
Parameters:
- userId (optional, integer): ID of the user to retrieve.
Headers: Authorization (Bearer Token) - The API requires authorization to access user profiles.
Expected Response:
- Success (200): Returns user details in JSON format, including fields id, name, and email.
- Error (404): Returns “User not found” if the userId doesn’t match any users.

Make The Most Of Hoppscotch for API Documentation

Consistency in Naming and Structure

Create a standardized naming convention for collections, folders, and requests. Consistency helps users navigate the documentation and quickly find relevant endpoints.
Use Detailed Descriptions

Don’t assume that others know the context behind your API requests. Provide clear, concise descriptions for each endpoint, method, and parameter, ensuring all necessary details are included.
Test and Document Error Cases

Documenting only the successful cases often leaves out crucial information. Make sure to test and describe possible error responses, including status codes and error messages. This helps users understand how to handle exceptions.
Leverage Comments and Annotations

Use comments within your collections to provide additional information where needed. Comments are an excellent way to explain complex requests or add insights about endpoint usage, without cluttering the main documentation.
Keep Documentation Updated

APIs often evolve, with endpoints being added, modified, or deprecated. Ensure you review and update your Hoppscotch documentation regularly to maintain accuracy.

Advantages of Hoppscotch for API Documentation

Intuitive Interface

Hoppscotch’s interface is simple, clean, and easy to navigate. Unlike heavier tools, it doesn’t require extensive setup or a steep learning curve, making it accessible for both experienced developers and newcomers.
Real-time Feedback

By providing instant responses to API requests, Hoppscotch enables real-time validation of documented endpoints. Developers can directly verify the accuracy of the documentation as they test endpoints.
Open-source Flexibility

Being an open-source tool, Hoppscotch can be customized or integrated into existing workflows. Developers can contribute to its codebase, and teams can build on its functionality to better suit their needs.
Team Collaboration Features

Hoppscotch's real-time collaboration supports dynamic documentation workflows, ideal for agile teams where multiple members contribute to or review API documentation.
Support for Multiple API Types

While primarily used for RESTful APIs, Hoppscotch also supports GraphQL and WebSocket requests, making it versatile and suitable for various API documentation requirements.

Hoppscotch offers a comprehensive, user-friendly solution for API documentation. Its interactive interface, real-time testing capabilities, and collaboration tools make it a strong alternative to traditional API documentation tools. Developers can create robust, accurate documentation that enhances API usability by organizing collections, utilizing environment variables, and carefully documenting both successful and error responses.

Star 🌟 Hopscotch On Github

Did you know that on The Handy Developers' Guide, you can get bite-sized, hands-on tutorials on various topics and languages to fit your busy lifestyle?