Forem: Apidog

Top API Technologies and How to Write Docs for Them

YukioIkeda — Wed, 26 Mar 2025 08:56:11 +0000

In the ever-evolving world of software development, APIs (Application Programming Interfaces) are the backbone of modern applications. They enable different software systems to communicate and exchange data, fostering innovation and seamless integration. Documenting these APIs effectively is crucial for developers to understand, implement, and maintain them.

This blog post explores the top API technologies and provides a practical guide on how to document them using Apidog, a powerful API design, testing, and documentation tool.

Top API Technologies

Here's a rundown of the most popular API technologies used today:

REST (Representational State Transfer): A widely adopted architectural style that uses standard HTTP methods (GET, POST, PUT, DELETE) to access and manipulate resources. REST APIs are known for their simplicity, scalability, and ease of use.
SOAP (Simple Object Access Protocol): A more complex, XML-based protocol that provides a structured way for applications to communicate over a network. SOAP APIs often require a WSDL (Web Services Description Language) file to define the API's contract.
GraphQL: A query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL allows clients to request specific data, reducing over-fetching and improving efficiency.
gRPC (gRPC Remote Procedure Calls): A high-performance, open-source framework developed by Google. gRPC uses Protocol Buffers for serialization and HTTP/2 for transport, making it efficient and suitable for microservices architectures.
WebSocket: A communication protocol that provides full-duplex communication channels over a single TCP connection. WebSockets are ideal for real-time applications like chat applications and live data streams.
SSE (Server-Sent Events): A server push technology enabling a server to automatically send data updates to a client over HTTP. Unlike WebSockets, SSE is unidirectional (server to client), making it suitable for applications where the server needs to push updates without the client explicitly requesting them.

REST API Documentation

Apidog is an all-in-one platform that streamlines the API development lifecycle, from design and testing to documentation. Let's see how to use Apidog to document different API technologies effectively.

Apidog advocates for the API-design first approach. Start by defining your API specifications with Apidog's intuitive visual editor. Documenting a REST API involves:

Defining Endpoints: For each endpoint, specify the path, request method (GET, POST, PUT, DELETE), request parameters (query, path, header, body), and request body schema.
Describing Parameters: Provide clear descriptions for each parameter, including its name, type, whether it's required or optional, and any default values or constraints. Utilize the Type Editor to define data types, formats, and constraints visually.
Defining Responses: Specify all possible response statuses, the data format (JSON, XML), the response schema (using JSON Schema), and provide example responses.
Using Components: Reuse common parameters and responses using Apidog's component feature for consistency and efficiency.
Enhance Documentation with Custom Fields: With Customized Fields, you can add fields such as "Authorization Required," "Response Format," or "Rate Limiting Policy".
Automated Documentation: Apidog automatically generates clear and up-to-date API documentation.

Here is an example of REST APIs:
Pet Store API

SOAP API Documentation

While SOAP is a legacy protocol, it is still critical for enterprise systems. Documenting SOAP APIs involves handling XML-based requests and responses.

Define Endpoints: Set the endpoint URL and choose the POST method.
Configure XML Settings: In Apidog, use the XML settings to define namespaces and elements, which will help validate the SOAP responses.
Provide XML Examples: Create XML examples, and automatically generate documentation.

Here is an example of SOAP APIs:
WebService API
MasterCard API

GraphQL API Documentation

GraphQL's schema-driven approach makes it ideal for clear documentation. With Apidog:

Use Markdown to write schema definitions, queries, and mutations directly.
Add detailed descriptions for fields, parameters, and response structures in Markdown comments.
Document Example Queries: Include real-world examples of how to use your API.

Here is an example of GraphQL APIs:
GitHub GraphQL API

gRPC API Documentation

Apidog simplifies documenting gRPC APIs by:

Importing Proto Files: Import your .proto files that contains clear comments of gRPC service.
Generate Markdown Documentation: Use protoc-gen-doc to convert .proto files into Markdown documentation.
Host and Share Documentation: Host the documentation for team access by creating a new HTTP project and use Markdown file in Apidog.

Here is an example of gRPC APIs:
Protocol Documentation

WebSocket API Documentation

WebSockets require documenting the connection handshake and message formats. In Apidog:

Describe API: use Markdown to write a detailed description of your WebSocket API. Include information about its purpose, endpoints, and usage scenarios.
Show Message Structure: By using Apidog’s schema components, it can define the JSON structure of a chat message.
Organize and Publish: Organize your documentation and set the lifecycle of the API.

Here is an example of WebSocket APIs:
Coinbase WebSocket API

SSE API Documentation

For documenting SSE APIs:

Clearly describe how the server sends events and what data they contain.
Document the format of the data stream.

Here is an example of SSE APIs:
Anthropic SSE API

Key Takeaways

Choose the Right Tool: Apidog is a powerful all-in-one platform for documenting almost all types of APIs.
Embrace API-Design First: Start with the API's design to ensure it meets the needs of both providers and consumers.
Be Thorough: Provide clear, concise, and accurate documentation for all aspects of your API.
Utilize Examples: Include real-world examples to help developers understand how to use your API effectively.

By following these guidelines and using Apidog, you can create comprehensive and user-friendly API documentation that promotes adoption, reduces support costs, and drives innovation.

Best Practices for Developing Non-English APIs

Ismail Kamil — Thu, 26 Dec 2024 03:34:18 +0000

OpenAPI (Swagger) is the most popular API design tool, and Postman is the most widely used tool for API development and debugging. However, if your team's working language is NOT English, Swagger and Postman might not be the best choices.

I have tried a tool called Apidog, and from the perspectives of API design, API development and debugging, API mocking, and API documentation, it represents best practices for developing non-English APIs.

API Design

Swagger is the standard tool for API design. However, if the API is intended for non-English usage, Swagger can be quite challenging to read and write. Mastering Swagger itself presents a significant challenge.

This often leads many non-native English teams to abandon defining API specifications, instead opting to write code to achieve functionality. Consequently, the APIs developed may become difficult to call and collaborate on.

Apidog offers a great alternative for designing APIs in non-English languages.

Firstly, the API design in Apidog is entirely visual. You don't need to grasp the complicated API schema syntax in Swagger; you can design compliant APIs visually. You can easily reference schemas visually and use components to improve the efficiency and standardization of API design.

Secondly, Apidog thoughtfully provides a "title" attribute for non-English developers, which describes the property's name in your native language, corresponding with the English "name" attribute. (Currently supporting Japanese and Portuguese)

In addition to visualized design, Apidog automatically generates mock responses in the current language when creating response examples. (Supports all languages)

API Documentation

When you create an API spec in a non-English language, you can publish multilingual API documentation in Apidog. (Supports all languages)

API Development and Debugging

No matter what language your API spec is defined in, Apidog allows you to send requests in any language you need by generating the request body. (Supports all languages)

API Mocking

You can also generate corresponding Mock APIs based on your spec. (Supports all languages)

Overall, Apidog provides a comprehensive solution for non-English speaking developers, offering a seamless experience in designing, documenting, developing, and testing APIs. This tool empowers developers to focus on building functionality without being hindered by language barriers, effectively bridging the gap between different languages in software development.

🦴 Try Apidog 🐶

How I Use My Own Product to Maintain Its Help Docs

YukioIkeda — Mon, 23 Dec 2024 10:15:03 +0000

The Past

I am the product manager for the SaaS product, Apidog. It has been online for over two years and offers a wealth of features related to API development, testing, and documentation. This also means it requires a comprehensive set of help documents.

Previously, we used the tool Docusaurus to maintain our Help Docs. It is a document tool based on Markdown with rich customization features.

However, using this tool was challenging for us.

Firstly, it is a code-based tool, which might be developer-friendly, but for a product manager, modifying anything meant pulling code and making a merge request. I spent a great deal of time trying to understand the logic of Git. This also led to us often neglecting minor optimizations in the documentation because it was simply too cumbersome.

Secondly, it was entirely based on Markdown, which has very limited support for styling beyond plain text. For a long time, our help documentation lacked a decent homepage.

Third, Docusaurus had poor support for multiple languages. Our tool itself offers several languages (English, Japanese, with more to come) and provides help documentation in English and Japanese. However, in Docusaurus, these could only be deployed as two completely separate projects. Moreover, because the Japanese help was maintained by our Japanese operations team, there were often updates in the English documentation that were not synchronized to Japanese.

In mid-2024, we suddenly realized that Apidog itself is a documentation tool (though primarily an API documentation tool). Would it be a good idea to use Apidog directly to maintain its help documentation?

Experimentation

In fact, Apidog is a fairly powerful API documentation tool. It supports visual API design, Markdown and API doc mixing, custom navigation, and custom domains. Many companies use it to maintain their API documentation.

But using Apidog entirely to maintain help documentation was a new experiment.

I thought I should try it. If I could create a beautiful example, perhaps companies using Apidog for API documentation might also use it for their help documentation.

I began this experiment around Septemper 2024.

Apidog directly supports Markdown, so the first step was simple: migrate the documentation originally maintained in Docusaurus over.

One great feature is that Apidog supports a much more powerful syntax than native Markdown. For instance, it includes effects like Card, Image Background, Step, Highlight, and more.

I spent considerable time transforming the existing Markdown help documents, making their style more beautiful and modern.

I also quickly created a document homepage, remedying a previous regret.

However, during this process, I also discovered some shortcomings in Apidog’s documentation capabilities.

For example, it doesn’t support document slugs and uses numbers as URL suffixes instead, which is obviously not good for SEO.

Additionally, it only supports searching within document titles, not the content, which is clearly inadequate for help documentation.

Fortunately, I am the product manager for this product. For me, these are two high-priority demands in the backlog.

This was in October 2024.

New Features

On October 25th, we released version 2.6.26. This version supported custom Slugs and automatic Slug generation based on document names.

On November 15th, version 2.6.31 supported Algolia DocSearch, allowing for full-text document searches.

During this period, we added a Support module to the original Help Docs, with each page representing a frequently asked question from users.

At the same time, we used the API version feature to build Japanese Help Docs. We support publishing multiple versions of documents, and readers can choose which version to read on the page. You can consider each version as a revision or as a different language.

So now, I can directly switch between English/Japanese on the help documentation.

Now, I have a set of beautiful, powerful help documents maintained using our own product. I equipped it with custom domains and navigation, and it looks perfect.

The best part is that there is no longer a need for a pull and MR each time, and each product manager can directly maintain the help documentation for their newly launched features. Efficiency and effectiveness have increased significantly compared to before.

Our technical support team can also directly maintain frequently asked questions from emails or Discord into the Support section, just using Apidog.

All images can be directly uploaded to Apidog space without needing special tools to upload them to a CDN.

In early December, our new version of Apidog Help Docs went live. You can read it at https://docs.apidog.com.

Now I can proudly say that Apidog is an excellent tool for maintaining help documentation and API documentation. Most of the above features are free.

Using Apidog to maintain our help documentation was the best decision I made in the second half of 2024.

🦴 Try Apidog 🐶

How to Build Your Frontend Apps 10x Faster!

Ismail Kamil — Thu, 05 Dec 2024 10:04:48 +0000

One of the biggest challenges in frontend development is the waiting game. When the API is not yet ready, the frontend team is often left with no choice but to hard-code the response data into the UI. This is a major bottleneck that hinders frontend development efficiency.

However, there is now an extremely efficient solution that allows you to mock any API data in just 1 min and provide it to the frontend team as an API.

The best part is that -- the mocked data is dynamic and almost indistinguishable from the real data.

Let's start.

Get the Required JSON.
Use Apidog to Create an Endpoint with your JSON.
Save and Get the Mock URL. Done!

Step 1: Get the Required JSON

When preparing to mock an API, obtaining the necessary JSON data is crucial. This JSON data represents the structure of the response your frontend application expects from the API. There are several methods for acquiring this JSON data:

Collaboration with Backend Team: Engage in discussions with your backend colleagues to get a precise understanding of the required data structure.
API Documentation Exploration: Review any existing API documentation that details the endpoints and typical response formats you can anticipate.
Existing Sample Data: If the application being developed is an enhancement or revision, older versions or similar projects may have existing sample data that can be used as a reference.
Manual JSON Construction: When data is unpredictable or not yet modeled, you might manually draft a sample JSON template based on expected fields and types.

Example JSON

Let’s consider the following example JSON structure for our mock API:

{
    "id": 93189357,
    "firstName": "Richard",
    "familyName": "Mertz",
    "email": "Joel_Bergstrom64@yahoo.com",
    "phone": "(588) 534-9295",
    "streetAddress": "789 Noel Fall",
    "city": "East Olgastead",
    "state": "Missouri",
    "zipcode": "04493",
    "gender": "female",
    "birthday": "2010-01-31",
    "bio": "assist advocate  🦝",
    "userAgent": "Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 5.2; Trident/6.0)"
}

This is a fictional user JSON containing several common fields.

Now just copy it. If you've already such a JSON, this step will take you no more than 10 seconds.

Step 2: Use Apidog to Create an Endpoint with Your JSON

Apidog is an efficient tool for API development and mocking. First, download it from Apidog's website and register an account.

Once that's done, click "create a new endpoint" within your project.

The only field you must fill in is the endpoint path—use something like /user/{id} for accessing mock data.

Next, scroll to the Response section and click on the "Generate from JSON etc." button.

Paste your JSON data from Step 1 and click OK. Apidog will automatically generate the response schema and example based on your JSON.

Finally, click Save to save the endpoint.

This whole process, excluding download and registration, only takes about 30 seconds.

Step 3: Get the Mock URL

After saving your endpoint in Apidog, you'll find a mock module within the endpoint details. This module provides you with a mock URL. Simply click on the mock URL to copy it.

Next, paste this URL into your browser.

Congratulations! You now have a working mock API!

It's not just a static response; every time you refresh the page, you'll notice that the content changes, simulating the behavior of a real API. This dynamic response feature is invaluable for testing and developing frontend applications in a realistic environment without waiting for the backend to be ready.

How it works

Apidog operates as a robust platform for API development and mocking by intelligently interpreting your input JSON data. Here's a closer look at its functionality:

JSON Parsing and Data Schema Generation:

When you paste your JSON into Apidog, it parses the structure to create a corresponding data schema, establishing an API specification. This schema defines the expected format and type of data for each property in the JSON.

Mock Engine:

Apidog includes an integrated mock engine, effectively functioning as a lightweight mock server that runs locally on your PC. This engine uses your API specification to dynamically generate mock data.

For dynamic responses, Apidog utilizes the names of your JSON properties to apply appropriate mock functions from faker.js. These mock functions are responsible for producing realistic, random data. Each browser refresh triggers the generation of new mock data, giving the illusion of interacting with a real API.

Static Mock

If you prefer consistent outputs on every request, you have the option to switch the mock data from dynamic to static effortlessly:

During the JSON parsing process, Apidog saves the data as a response example.
To make use of this static option, go to Settings, navigate to Feature Settings, and access Mock Settings.
Change the default mock type to "Response example first." By doing this, the mock API will consistently return the saved response example, making your test data stable and predictable.

Custom Mock

If the automatically generated mock output for a specific property doesn't meet your requirements, Apidog allows you to customize this property's mock behavior easily.

Navigate to the Response Schema section for the relevant endpoint.
Locate the property whose mock needs adjustment. In the mock field of this property, choose a suitable function that aligns with your desired output.

Cloud Mock

The mock API we've discussed so far is hosted locally. However, if you need to share it with others or give access outside your local environment, Apidog provides a cloud mock feature.

To enable this feature, Go to Settings, navigate to Feature Settings, and access Mock Settings. Toggle on the Cloud Mock option.

Once enabled, your API will be accessible from the cloud. Simply copy the cloud mock URL provided and open it in a browser to access it. This feature makes it easy to share your mock API with team members, stakeholders, or testers who need to access it remotely.

For example, try visiting this cloud mock address to see it in action:
https://mock.apidog.com/m1/644296-613644-default/user/1

This is truly a comprehensive Mock API solution.

Apidog claims to be the REAL API Design-first Development Platform, and it can be used for Design, Debug, Test, Document, and Mock.

In practice, it is very user-friendly and effectively enhances the work efficiency of front-end, back-end, and testing teams.

You should give it a try as well.

🦴 Try Apidog 🐶

Apidog Official Website

Postman vs Apidog: Choosing the Suitable API Development Tool

YukioIkeda — Wed, 09 Oct 2024 07:46:21 +0000

Postman has long been the go-to tool for API developers, offering a robust and feature-rich platform to design, test, and debug application programming interfaces. However, a new contender has emerged in the form of Apidog - a promising newcomer that is quickly gaining traction in the API management space.

Both Postman and Apidog aim to streamline the API development lifecycle, providing users with an array of functionalities to construct HTTP requests, inspect responses, and validate API behavior. From API design to testing and mocking, these tools share a common goal of empowering developers to build better, more reliable APIs.

However, the core difference between the two lies in their target user groups. Postman is primarily designed for API consumers, while Apidog is more suitable for API development teams.

Postman: Ideal for API consumers

Postman has established itself as an indispensable tool for API consumers, offering a suite of features that address the fundamental needs of interacting with APIs efficiently and effectively. It is particularly advantageous in several key scenarios:

Ideal Use Cases:

Rapid Request Creation and Execution: Postman is exceptional for quickly crafting and sending requests to an already developed API. Its intuitive interface and robust feature set allow users to easily configure different HTTP methods, manage headers, and specify parameters, enabling precise and efficient API interaction.
Organizing Requests with Collections: Users can assemble and organize their API requests into Collections, facilitating the sequential sending of multiple requests. This is particularly useful in scenarios where a series of requests are required to achieve a specific outcome, such as testing a workflow or sequence of API calls.
Forking Existing Collections: One of Postman’s unique strengths is the ability to fork collections created by others. Developers can easily duplicate publicly available Postman collections, modifying them to fit their particular needs without starting from scratch. This feature saves time and encourages collaboration by allowing developers to build upon existing work.
Visualizing with Postman Flow: Postman Flow provides a powerful way to create request flows and visual representations of API interactions. This feature helps developers design complex request chains and enhances clarity in understanding how different requests interact within an API ecosystem.

Limitations:

Despite its benefits, Postman does have several limitations that may affect its suitability for certain development scenarios:

Limited Support for APIs in Development: Postman is not ideally suited for APIs that are still under development. Frequent API changes necessitate constant rewriting of requests and scripts, adding additional overhead for developers when working with APIs that are evolving rapidly.
Detached API Specification: In Postman, the API specification and collections are distinct from one another, preventing the establishment of a single point of truth for API data. This separation can lead to discrepancies and confusion, as updates to the API specification may not automatically reflect in existing collections.
Collection Run Limitations: Postman imposes limitations on the number of collection runs one can execute for free. Users have a cap of 25 runs per month, after which they must switch to a paid plan to continue running their collections, potentially adding unanticipated costs for small teams or individual developers working on budget constraints.

Apidog: Ideal for API development teams

Apidog emerges as a valuable tool for API development teams, particularly those engaged with APIs that are actively under development. It provides features that serve collaborative and dynamic environments, enabling teams to work more effectively and with greater agility.

Ideal Use Cases:

Visual API Specification Creation: Apidog shines in environments where API specifications are frequently evolving. It enables teams to create and manage API specs visually, allowing seamless updates and changes, which is particularly beneficial during the iterative development phases.
Visual Test and Assertion Creation for QA Teams: Quality assurance teams can leverage Apidog's ability to create visual tests and assertions, streamlining the testing process. Its compatibility with Postman scripts ensures that existing test scripts can be integrated without significant rework, fostering greater flexibility and ease of transition.
Real-Time Updates with API Spec Changes: One of Apidog’s standout features is its ability to reflect changes in API specs immediately across all related requests. This feature ensures that tests and requests remain current with the latest API developments, reducing the need for manual updates and minimizing errors.
Logical and Data Flow Visualization: Developers can visually orchestrate different requests, defining logical relationships and data flows between them. This capability helps in designing complex API interactions and ensures data passes correctly through various request chains.
Auto-Generated Requests and Mock Responses: Apidog can automatically generate requests and mock responses based on API specifications. This feature facilitates rapid prototyping and testing, allowing teams to simulate API behavior before the backend is fully implemented.
Unlimited Collection Runs: Unlike some other tools, Apidog does not restrict the number of collection runs, enabling development teams to conduct extensive testing and iterations without incurring additional costs.

Limitations:

Despite its advantages, Apidog has certain limitations which may not cater well to all user scenarios:

Complexity for API Consumers: For API consumers who primarily need to send requests, Apidog’s interface and setup process may seem more complicated compared to simpler tools. This complexity can be a barrier for users who just need quick and straightforward API interaction.
Lack of Flow Visualization for Diagram Creation: While Apidog excels in many aspects of managing and testing APIs, it falls short when it comes to offering features like Postman Flow, which allows developers to create visual diagrams of their API interactions. This absence can make it less appealing for users who prioritize visual representations of workflow logic.

Feature Comparison: Postman vs Apidog

Here is a simple comparison of core features of Postman and Apidog.

		Postman	Apidog
Sending Requests
	HTTP	✅	✅
	WebSocket	✅	✅
	SOAP	✅	✅
	GraphQL	✅	✅
	gRPC	✅	✅
	SSE	✅	✅
API Designing
	Design APIs visually	🚫	✅
	Import/export OAS	✅	✅
	Define and reuse schemas	🚫	✅
	Parse API specification from request	🚫	✅
	Generate example automatically	🚫	✅
	Branches	✅	✅
API Debugging
	Pre/post-request scripts	✅	✅
	Response validation	🚫	✅
	Connect to databases	🚫	✅
	Multiple services	🚫	✅
	Reference other programming languages	🚫	✅
API Testing
	Visual Orchestration with no code	🚫	✅
	Visual assertions	🚫	✅
	CI/CD	✅	✅
	Run collections	25/month	Unlimited
	Scheduled task	✅	✅
	Performance test	✅	✅
	Online test reports	🚫	✅
	Self-hosted runner	🚫	✅
API Documentation
	Custom domain	🚫	✅
	Custom documentation layout	🚫	✅
	Markdown pages	🚫	✅
	Versioning	🚫	✅
API Mocking
	Fixed response mocking	✅	✅
	Smart mock engine	🚫	✅
	Cloud mock server	🚫	✅
	Customized mocking scripts	🚫	✅
	Self-hosted mock server	🚫	✅
IDE plugin		VS Code	IDEA