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.
Table of Contents
- 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.
-
Parameters: Add any query parameters in the “Params” tab, like filtering options (
-
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
, andemail
. - Error (404): Returns a "Not Found" message if the user ID doesn’t exist.
- Success (200): Returns a JSON array of user details with
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
, andemail
. -
Error (404): Returns “User not found” if the
userId
doesn’t match any users.
-
Success (200): Returns user details in JSON format, including fields
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?
Top comments (2)
Detailed work Dumebi 🔥 How easy do you think the process is for a complete beginner?
Uhm, I think it's fairly easy if you know what you're doing tbh.
I think the documentation could be better, but good all the same.