A documentation the API It explains how developers and systems should interact with a programming interface. Good documentation presents endpoints, HTTP methods, authentication, parameters, payloads, responses, errors, usage limits, examples, and versioning rules clearly enough for someone to implement the integration without having to discover the API's behavior through trial and error.
It can be written manually, generated from a specification like OpenAPI, or combine automatic references with guides, tutorials, and real-world examples. The more critical the API is to customers and partners, the more important it is to treat its documentation as part of the product itself.
Summary
- What is API documentation and who is it for?
- What information should every endpoint document?
- How HTTP methods, parameters, authentication, and errors should be explained.
- How OpenAPI helps keep documentation readable by both humans and machines.
- Why examples, sandboxes, changelogs, and versioning reduce integration errors.
- How to structure documentation that remains useful as the API evolves.
What is API documentation?
API documentation is the set of information that describes how to use an API. Application Programming InterfaceIt functions as a communication contract between the API provider and the developers who need to use it.
For an HTTP API, the documentation should answer questions such as:
- Which URL should be called?
- Which HTTP method to use?
- How to authenticate;
- Which parameters are mandatory and which are optional?
- What format to send in the request body;
- What response to expect in case of success?
- What errors can occur?
- What limits and rules need to be respected?
A technical reference, however, doesn't need to be the only type of content. More complete documentation can combine endpoint references, a quick start guide, concepts, integration recipes, code examples, tutorials, and troubleshooting.
What should API documentation include?
The specific elements vary depending on the protocol and the complexity of the API, but some items are fundamental in HTTP APIs.
| Element | What should you explain? | Example |
|---|---|---|
| Endpoint | Resource and URL accessed | /documents/{id} |
| HTTP method | The intention of the operation | GET, POST, PUT, PATCH or DELETE |
| Authentication | How does the app verify your identity? | Bearer token, OAuth or API key |
| Parameters | Path values, query and headers | id, page, Authorization |
| Request body | Structure of the data sent | JSON |
| Response | Structure of the returned data | Status + JSON |
| Errors | What happened and how to fix it? | 401, 404, 429 |
| rate limit | Allowed number of calls | 500 requests/minute |
| Versioning | How are changes introduced? | /api/v1/ |
| Examples | Real requests and responses | cURL, JavaScript, Python |
Endpoint Description
An endpoint identifies a resource or operation available through the API. In an HTTP architecture, it typically combines a URL with a method.
Therefore, documenting only something like /documents It is insufficient. The consumer needs to know the difference between:
GET /documents;POST /documents;GET /documents/{id}.
Each operation must include its objective, method, URL, authentication, parameters, body, responses, and examples.
HTTP Methods
HTTP methods express the intent of the request. The current normative reference for most methods is... RFC 9110; PATCH is defined by RFC 5789.
GET
It requests the current representation of a resource. It is defined as a safe method: its semantics should not be used to request a state change desired by the client.
POST
It requests that the resource process the submitted content according to its own semantics. It is widely used for creation, but... POST does not necessarily mean "create".It can also initiate operations, execute commands, or send data for processing.
PUT
It requests that the target resource's state be created or replaced by the submitted representation. Therefore, the most accurate definition is not simply "edit a user," but rather replace the representation corresponding to the resource.
PATCH
This requires the application of a set of partial modifications. RFC 5789 was created precisely to differentiate this operation from the complete replacement performed with PUT.
DELETE
This requests the removal of the association between the resource and its current functionality. This does not necessarily imply that every byte related to the resource will be physically deleted from the server's storage.
Documentation may also need to explain HEAD, OPTIONS, or specific methods supported by the API. Avoid turning GET, POST, PUT, PATCH, and DELETE into a rigid CRUD rule when the implementation has a different semantic meaning.
Path parameters, query, and headers
The documentation needs to show not only what parameters exist, but also their type, format, mandatory nature, allowed values, limits, and default behavior.
The main ones include:
- path parameters: are part of the route itself, such as
/usuarios/{id}; - query parameters: appear in the query string, such as
?page=2&status=active; - headers: They carry metadata, credentials, accepted formats, and other request controls;
- request body: It carries the representation or the main data sent to the operation.
Mature documentation also explains limitations such as maximum size, string length, date formats, enums, mutually exclusive fields, and conditional rules.
Request and response examples
Examples bridge the gap between "understanding the reference" and getting the first integration to work.
A well-documented endpoint should show at least one valid call and its response. More complex operations should also introduce errors and alternative scenarios.
When it makes sense, provide examples in cURL and in the languages most commonly used by the API's audience. However, examples should not replace the formal description of the fields, because a single payload does not demonstrate all possible rules.
Status codes and error structure
It's not enough to write "400 = error" and "500 = server problem". The documentation must explain... why Each code appears along with what the integrator can do next.
- 200 OK: The request was processed successfully.
- 201 Created: A new feature has been created;
- 204 No Content: The operation was completed without a response from any body.
- 400 Bad Requests: The request could not be processed as sent;
- 401 Unauthorized: Valid authentication credentials are missing;
- 403 Forbidden: The identity may be known, but the operation is not authorized;
- 404 Not Found: The feature was not found or is not disclosed to the consumer;
- 429 Too Many Requests: A request limit has been exceeded;
- 5xx: There was a server-side or infrastructure failure.
When an API needs to standardize the content of errors, the RFC 9457 — Problem Details for HTTP APIs It offers a reusable framework for transmitting machine-readable information without inventing a different error format for each endpoint.
Authentication and authorization
The documentation should explicitly explain how to obtain credentials, where to send them, and what permissions they have.
Possible options include API keys, bearer tokens, OAuth, and other mechanisms appropriate to the architecture.
It's also important to make this clear:
- If test and production credentials are different;
- If tokens expire;
- how to renew them;
- What scopes or permissions are needed?
- How to revoke a compromised credential.
Rate limits
Rate limits protect service stability and help distribute capacity among consumers. The documentation should explain how the quota is calculated, the time window for which it is applied, and what response occurs when it is exceeded.
Na Current documentation for the ZapSign APIFor example, the general limit for public endpoints is 500 requests per minute, applied per IP or authentication token. Upon reaching the limit, new calls within that window receive HTTP 429.
What is OpenAPI and what is its relationship to documentation?
A OpenAPI Specification It is a language-independent standard for describing HTTP API interfaces in a structured way.
In October 2026, the most recent version is... OpenAPI 3.2.1, published on September 10, 2026.
An OpenAPI description can represent, among other elements:
- available servers;
- paths and methods;
- parameters;
- request bodies;
- data schemas;
- answers;
- security methods;
- examples;
- Callbacks and webhooks.
The benefit is that the same description can serve both humans and tools. Generators can transform the OpenAPI file into a navigable reference, clients, tests, mocks, or other artifacts of the API lifecycle.
The official guide Learn OpenAPI It explains the specification structure and shows how to document endpoints, parameters, bodies, examples, security, and webhooks.
Are OpenAPI and Swagger the same thing?
Not exactly. The specification formerly known as the Swagger Specification is now called the OpenAPI Specification.
Today swagger It primarily refers to an ecosystem of tools built around OpenAPI.
Among them:
- Swagger Editor: helps in writing and validating descriptions;
- Swagger UI: It transforms an OpenAPI description into an interactive documentation interface;
- Swagger Codegen: It uses the description to generate client code and server structures.
A Swagger UIFor example, it allows you to view and interact with operations described by OpenAPI directly in the browser.
This means that the most accurate recommendation is not "document your API in Swagger," but rather: Consider defining your API in OpenAPI and using tools like Swagger to edit, validate, or render that definition..
⚠️ Also check out these related articles 👇
➡️ Understand how an electronic signature API works.
➡️ See how the ZapSign API works.
➡️ Learn about the consequences of poor document management
How to create good API documentation in 10 steps?
1. Start with the quickstart
Before presenting hundreds of endpoints, help the developer complete a single valid request.
A good quick start should show:
- How to create an account or gain access;
- How to generate credentials;
- Which URL to use?
- a minimum requirement;
- a valid answer;
- The next step after the test.
2. Separate reference guides and concepts.
Technical references answer “what fields exist?”. A guide answers “how do I solve this problem?”. Mixing everything on a single page makes it difficult to find information.
An efficient structure can separate:
- How to get started;
- Authentication;
- Concepts;
- API Reference;
- Webhooks;
- Errors;
- Changelog;
- FAQ or troubleshooting.
3. Use real-world, copyable examples.
Examples should actually work or faithfully reproduce the API contract.
Avoid examples with outdated fields, incorrect production URLs, or responses that no longer match the current schema. This type of inconsistency quickly destroys trust in the documentation.
4. Also document the errors.
An integration isn't just about a successful path. Show invalid authentication, incomplete payload, insufficient permissions, missing resource, exceeded limit, and relevant temporary failures.
A ZapSign APIFor example, it maintains its own error status page explaining responses such as 400, 401, 402, 403, 404, 406, and 429.
5. Provide a sandbox environment.
Testing an API in production can generate documentation, charges, communications, or actual changes. When possible, provide an isolated environment.
A ZapSign keeps its sandbox separate from production.The global test endpoint is https://sandbox.api.zapsign.com.br/api/v1/while production uses https://api.zapsign.com.br/api/v1/.
The documentation makes it clear that documents created in the sandbox have no legal validity, which is essential information to avoid confusion between environments.
6. Keep authentication and security very clear.
Never force the integrator to guess where to put your key.
Na ZapSign documentationFor example, static API tokens and JWTs are described. The JWT documentation further explains that the access token expires and can be renewed.
Also, include clear warnings that credentials should never be exposed in public repositories, client-side code, or real-world examples published by mistake.
7. Offer interactive documentation when it is helpful.
An interactive interface can allow the developer to change parameters and execute a call without manually assembling the entire request.
Tools like Swagger UI do this using OpenAPI. However, Postman You can generate documentation from collections, including authentication information, parameters, requests, responses, and examples.
Interactivity, however, does not replace conceptual explanations. A "Try it" button helps to test, but it alone does not explain why an operation should be used.
8. Version changes incompatible
When a change could break existing customers, the supplier needs to define a compatibility strategy.
A ZapSign's current policyFor example, it indicates that the API is in V1 and considers changes such as adding endpoints, new optional parameters, new response properties, and new webhook types to be compatible.
This has an important consequence for consumers: they should not program parsers that break simply because a response has gained a new property.
9. Document depreciation and migration
When an endpoint is to be replaced, simply removing it from the documentation is not sufficient.
Report:
- What is being discontinued;
- which feature will it be replaced by;
- From when?
- What impact is expected?
- How to migrate.
Since 2025 the RFC 9745 It also defines the HTTP header. DeprecationThis allows you to programmatically signal that a feature has been or will be discontinued. It can be combined with migration documentation and, where appropriate, with the header. Sunset.
10. Keep code and documentation synchronized.
The biggest problem with documentation isn't that it's short: it's that it's wrong.
A reference stating that a field is optional when the API requires it, an example with an outdated version, or an incorrect status code costs development and support time.
Therefore, incorporate documentation into the development cycle. Changes to endpoints should include updated specifications, examples, changelogs, and tests before publication.
How can I use OpenAPI to keep my documentation up to date?
One approach is to treat the OpenAPI description as a structured source of the API contract.
According to Official documentation of the OpenAPI InitiativeThe description can be written in JSON or YAML and represent the main components of the interface.
Therefore, different tools can reuse the same definition for:
- render references;
- Validate the API structure;
- create mocks;
- Generate SDKs or helper code;
- generate tests;
- Feed internal catalogs.
This reduces the risk of manually maintaining multiple independent descriptions of the same operation.
But an OpenAPI definition doesn't eliminate the need for editorial content. Tutorials like "how to make your first subscription via the API," architectural decisions, and guidance on retries still need to be written with the developer journey in mind.
How do you evaluate if API documentation is good?
A simple test is to imagine a developer who has never spoken to their team and try to answer whether they could:
- understand what the API is for;
- to obtain a credential;
- Execute the first request;
- interpret the answer;
- to understand a mistake;
- Testing without affecting production;
- Discover the call limit;
- to know what changed between versions;
- Discover how to ask for help.
If the answer is "no" to several of these points, the documentation probably still relies too heavily on internal knowledge.
What is the documentation like for the ZapSign API?
A Official ZapSign API documentation It includes introduction, authentication, sandbox, endpoints, webhooks, widget, rate limit policies, versioning, and error information.
The API is RESTful, works with JSON, and currently uses version V1. Authentication can be performed using a static token or JWT.
For those starting an integration, the documentation itself recommends using the test environment first.
If your intention is to learn specifically how to create, send, and track documents on the platform, see our [link/resource]. A complete guide to the ZapSign API..
Frequently asked questions about API documentation
It is a set of references, guides, and examples that explains how to consume an API, including endpoints, methods, authentication, parameters, responses, errors, and usage rules.
It should include quick start, authentication, endpoints, parameters, payloads, responses, errors, examples, rate limits, environments, versioning, changelog, and support guidelines.
OpenAPI is a standardized, language-independent specification for describing HTTP APIs in a structured way, allowing people and tools to understand their interface.
OpenAPI is the specification used to describe the API. Swagger is a set of tools that can create, edit, validate, or render OpenAPI descriptions.
The sandbox allows you to test authentication, payloads, errors, and integration flows without performing real operations or affecting the data and processes of the production environment.
Link the documentation to the development process, update specifications and examples along with the code, and maintain versioning, changelogs, and deprecation notices.

CEO of Henshin Agency and digital marketing consultant, fascinated by content marketing and an admirer of Japanese culture.

![[Banner] Legal validity of digital and electronic signatures: definitive guide with expert analysis](https://blog.zapsign.com.br/wp-content/uploads/2024/11/Banners-para-blog-Opice-Blum.webp)



