# OpenAPI Specification

The DeDi.global OpenAPI specification provides a comprehensive, machine-readable description of our entire API surface. This specification follows OpenAPI 3.0 standards and enables automated tooling, code generation, and integration workflows.

<a href="https://github.com/nfh-trust-labs/docs/blob/main/openAPI.yaml" class="button primary">Download OpenAPI specification</a>

### Usage Scenarios

#### Code Generation

Generate client SDKs in multiple programming languages:

```bash
# Generate Python client
openapi-generator-cli generate -i openAPI.yaml -g python -o ./dedi-python-client

# Generate JavaScript client  
openapi-generator-cli generate -i openAPI.yaml -g javascript -o ./dedi-js-client

# Generate Java client
openapi-generator-cli generate -i openAPI.yaml -g java -o ./dedi-java-client
```

#### API Documentation

Generate interactive documentation:

```bash
# Swagger UI
swagger-ui-serve openAPI.yaml

# Redoc
redoc-cli serve openAPI.yaml
```

#### API Testing

Test with tools like Postman, Insomnia, Newman, or Dredd.

### OpenAPI 3.0 Specification

The spec covers all endpoints, reusable schemas, authentication (Bearer token & cookie), response examples, and error codes. Core sections include security definitions, path operations, and component schemas.

### Integration Tools

* **Code Generation:** OpenAPI Generator, Swagger Codegen, AutoRest
* **Documentation:** Swagger UI, Redoc, Stoplight
* **Testing & Validation:** Spectral, Prism, Dredd

### Best Practices

* Pin generator versions and review generated code
* Customize documentation with interactive examples and error scenarios
* Maintain backwards compatibility, use semantic versioning, and document changes

### Specification Contents

* **Authentication:** Login/logout, API key management, token refresh
* **Core Resources:** Namespace, Registry, and Record CRUD
* **Advanced:** Domain verification, bulk import/export, webhooks, delegation
* **Administrative:** State management, version history, analytics

### Getting Started

1. Download the specification
2. Choose your tooling
3. Generate client code or documentation
4. Validate against the spec during development

### Related Resources

* [Postman Collection](/docs/api-tools-and-resources/api-tools/postman-collection.md): Interactive API testing
* [API Reference Documentation](/docs/dedi.global-developers/standard-apis.md): Human-readable docs
* [Developer Guide](/docs/dedi.global-developers/developer-documentation.md): Integration best practices
* [Authentication Guide](/docs/dedi.global-developers/standard-apis/access.md): Security implementation


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dedi-global.gitbook.io/docs/api-tools-and-resources/api-tools/openapi-specification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.