Adding API Code Examples

The system for adding and displaying API code examples in the Datadog documentation is a fully automated process. It is designed to ensure that examples are consistent with the API specifications and client libraries. The content within the API documentation section is auto-generated and should not be edited directly. Instead, changes must be made in the source repositories.

This system generates two primary types of examples:

1. JSON Payload Examples: Request and response body examples derived directly from the OpenAPI specification.
2. Client Library Examples: Complete, runnable code snippets for various programming languages (e.g., Python, Ruby) synced from dedicated client library repositories.

Sources: content/en/api/README.md, CLAUDE.md

High-Level Data Flow

The entire API documentation, including code examples, is built by aggregating information from multiple external sources. The core components are the datadog-api-spec repository for API definitions and various datadog-api-client-* repositories for language-specific examples. A Node.js script within this project, build-reference-pages.js, orchestrates the generation of pages and data files, which are then rendered by the Hugo static site generator.

The following diagram illustrates the high-level data flow for generating API documentation.

Generating JSON Payload Examples

JSON examples for request and response bodies are automatically generated from the example fields within the OpenAPI specification. The assets/scripts/build-reference-pages.js script is responsible for this process.

Build Script Logic

The script executes several key functions to parse the spec and create data files. The processSpecs function initiates the build for each API version (v1, v2) by reading the corresponding full_spec.yaml file.

The createResources function then iterates through each API endpoint defined in the spec and calls filterExampleJson to generate JSON for both the request body and all possible response codes. This output is saved into a examples.json file within each API section's directory (e.g., content/en/api/v1/dashboards/examples.json).

The following diagram shows the workflow for generating these JSON files.

Key Functions

Sources: assets/scripts/build-reference-pages.js

Sourcing Client Library Examples

Complete code examples for client libraries (e.g., Python, Ruby) are not stored in this repository directly. Instead, they are maintained in their respective datadog-api-client-* repositories and are automatically synced into the content/en/api/ directory during the build process.

This ensures that the examples shown in the documentation are always up-to-date with the latest version of the client libraries. The presence of files like content/en/api/v1/dashboards/CreateDashboard.py is a result of this synchronization.

This diagram shows the process of updating a Python client example and how it propagates to the documentation site.

Sources: CLAUDE.md, content/en/api/v1/dashboards/CreateDashboard.py

Rendering Examples on the Frontend

The final presentation of code examples is handled by Hugo templates. The partial template layouts/partials/api/code-example.html is responsible for creating the tabbed view that allows users to switch between different languages and see request/response payloads.

When a user views an API endpoint page, the following sequence occurs to render the examples:

This partial dynamically fetches the JSON data from examples.json for the payload tabs and reads the content of the synced files like CreateDashboard.py and CreateDashboard.rb to populate the language-specific tabs.

Sources: layouts/partials/api/code-example.html, content/en/api/v1/dashboards/CreateDashboard.py, content/en/api/v1/dashboards/CreateDashboard.rb

How to Contribute or Update an Example

Given the automated nature of this system, you must not edit API documentation files directly in this repository. Contributions must be made to the appropriate upstream source.

• To update a JSON payload example:

  1. Locate the relevant API endpoint definition in the datadog-api-spec repository.
  2. Modify the example field for the request body or response schema.
  3. Submit a pull request to the datadog-api-spec repository.
     Sources: content/en/api/README.md

• To add or update a client library code example:

  1. Identify the correct repository (e.g., datadog-api-client-python).
  2. Add or modify the example code within that project.
  3. Submit a pull request to that client library's repository.
     Sources: CLAUDE.md

Once changes are merged into the source repositories, the automated build process will pick them up and update the documentation site accordingly.

Conclusion

The API code example system is a robust, automated pipeline that ensures accuracy and consistency by treating external repositories as the single source of truth. It separates the concerns of API specification, client library implementation, and documentation presentation. This architecture allows for scalable and maintainable API documentation that stays in sync with the products it describes.