This repository contains OpenAPI specifications for InfluxData's various services. It provides a common place for shared API elements that are referenced by more specific API definitions.
This repository is organized as follows:
.
├── contracts/ # contains the aggregated openapi definitions; the "source of truth"
| └── svc/ # contains the aggregated openapi internal api definitions for each individual standalone service
├── scripts/ # contains various scripts to aid in the generation of the contracts
└── src/ # contains the raw openapi definitions
├── cloud/ # contains cloud specific openapi definitions
├── common/ # contains openapi definitions common to oss and cloud
| ├── parameters/ # contains common modular parameter definitions
| ├── paths/ # contains modular path definitions common to oss and cloud
| ├── responses/ # contains common modular response definitions
│ ├── schemas/ # contains common modular schema definitions
| ├── _parameters.yml # all parameters common to oss and cloud
| ├── _paths.yml # all paths common to oss and cloud
│ └── _schemas.yml # all schemas common to oss anc cloud
├── oss/ # contains oss specific openapi definitions
├── svc/ # contains service openapi definitions
| └── [service]/ # contains service specific definitions; similar structure to 'common'
├── cloud-priv.yml # defines the "private" cloud api ('/api/v2private')
├── cloud.yml # defines the cloud api
├── common.yml # defines the shared api elements (between cloud and oss)
├── oss.yml # defines the oss api
├── svc-[service].yml # defines an individual service api
├── quartz-oem.yml # defines the oem quartz api
└── unity.yml # defines the unity api
To learn how to add and update definitions, see How to contribute.
"Internal" API refers to a service API that is reachable directly (no gateway). A hypothetical example would be taskd talking directly to queryd without going through the gateway.
"External" API refers to the API that a gateway serves.
"Private" API refers to an API that is not published in docs, requires some alternate method of auth (superuser token), a ui/quartz specific routes, or is not committing to stability. "Public" API refers to a documented API used for normal use of the platform.
Since there is currently no code that supports API versioning, this repo will remain unversioned. Each swagger definition can define it's own api version, and consumers may test API changes on a branch, but until there is support for versioned APIs in code, we won't tag this repo.
Gateway refers to the entry point into our platform (whether it be a reverse proxy or some other router).
[client] -> [gateway] -> [service]
- An external
clientmakes a request for/api/v2/thing. gatewayfinds where to handle requests for/thingand forwards the request to that service.servicethen handles that request and responds to the client.
[service] -> [service]
- A
servicerunning inside the platform makes a request to another platformserviceat/thing. servicethen handles that request and responds to the client (requestingservice).
Although keeping the API spec "closer" to the implementing code (for example, in the same repository) might prevent drift between them, maintaining the service-specific ("internal") definitions in this repo provides the following benefits:
- Standard location: consumers aren't left wondering where they need to look for the current API contract of a service.
- Ease of access: given that many of the services are closed source, keeping the definitions in this public repo avoids the need for consumers to access private files.
- Simpler integration: integration of the service into the "external" API doesn't require updating the reference path.
The goal of this repo is to not only provide a central, trusted location for consumers of our external APIs, but also to provide a re-usable means for service maintainers to easily maintain their service API definitions. As repository adoption increases, we expect to remove duplicate definitions from our organization's codebase where appropriate, rather than provide API definitions in multiple locations.
Various tools can consume the OpenAPI specification and generate API client libraries for different programming languages.
A client application can then import a client library and interact with the API.
This repository, specifically the contracts directory, contains OpenAPI definitions to generate client libraries.
Similar to how Go (golang) has a standard library composed of smaller, single-purpose libraries, the contracts in this repo allow consumers to generate granular libraries that users can import as they need.
It is intended that an individual client library is generated for each service defined. cloud and oss definitions will continue to exist as monolithic definitions while we postpone splitting them up in order to preserve functionality. As this repository gains adoption, we would like to break subsets of the cloud and oss definitions into more granular services, such as query, write, and tasks.
These more specialized swagger definitions (similar to the mapsd, and managed-functions definitions), will allow the creation of granular libraries. The creation of more granular client libraries will allow developers to avoid bloat in their applications while still preserving the ability to consume a library to perform any action against our full API. Again, this modular workflow is preferred and benefits developers by not mandating that they consume a single client library that supports the entire API surface area.
As the "InfluxDB API" evolves and eventually gets versioned, we can continue to provide complete API definitions in ref, while allowing each sub-service (write, query, tasks, etc.) to evolve on its own.
The following example generates a mapsd client library for golang that consumers can use to interact with the mapsd service:
# prepare directory for generated library
mkdir -p /tmp/output
# generate golang library for mapsd (same pattern goes for any service or definition)
docker run --rm -v /tmp/output:/out -it swaggerapi/swagger-codegen-cli-v3 generate -i https://raw.githubusercontent.com/influxdata/openapi/master/contracts/mapsd.yml -l go -o /out/The library is then ready for use in an application:
import mapsd "<some-prefix>/mapsd/swagger"
...
mapsd.NewAPIClient.GetMapboxToken(context.Background())There are some limitations to this work.
InfluxDB UI requires that the definitions it consumes be oats-compatible and oats-consumable.
For example, an OpenAPI v3-compatible specification that oats doesn't support is the servers override, so we maintain separate files for definitions that contain servers overrides.
This is exemplified in cloud-priv.yml and its servers key - the main difference between cloud-priv.yml and cloud.yml.
To update and generate contracts, do the following:
- Clone this repository (
influxdata/openapi). - If you haven't already, install and run Docker.
- Review the guidelines.
- Edit
srcfiles. - With Docker running, run
make generate-allto generate new API contracts. - Commit the result, including the generated
./contractsfiles, and create a pull request.
Follow these guidelines to add and update specifications:
- Add and update paths and operations
- Add and update service definitions
- What to do when Cloud and OSS diverge
- Add tag content or describe a group of paths
If you're adding or updating paths and operations (get, post, etc.), follow our path template for summary, description, and example elements.
To add a service API definition, add the service specific components to a subdirectory inside src/svc and reference them from a file in src with the svc- prefix.
This allows product API maintainers to copy the service-specific ("internal") paths and components into the respective API definition (cloud, cloud-priv, or oss) without modifying references.
For more information on how to add a new service API definition, see src/svc/README.
For information on what to do when platform APIs drift, see src/README.
Use OpenAPI tags to group related endpoints (OpenAPI Paths).
Documentation generators that consume the API can use tags to provide navigation and additional information.
API reference docs
(OSS,
Cloud)
use the following tag elements and vendor extensions:
tagTags element: renders endpoint (Path) groups and trait tags in navigation menus--for example, Tasks.descriptionTag field: describes related Paths and their common features.x-traitTag: trueTag field: instead of grouping paths, the tag renders a topical section that contains supplemental information about the API.x-tagGroupsRoot element: groups and sortstagelements for navigation menus--for example, Data I/O endpoints.
To edit these elements, see the platform-specific files:
src/[platform]/tags.ymlsrc/[platform]/tag-groups.yml
For more information, see influxdata/docs-v2 /api-docs README.