{"id":20260373,"url":"https://github.com/influxdata/openapi","last_synced_at":"2025-04-11T01:32:56.449Z","repository":{"id":37052312,"uuid":"350541388","full_name":"influxdata/openapi","owner":"influxdata","description":"An OpenAPI specification for influx (cloud/oss) apis.","archived":false,"fork":false,"pushed_at":"2024-05-17T14:02:59.000Z","size":5787,"stargazers_count":17,"open_issues_count":143,"forks_count":10,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-03-24T22:42:07.641Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/influxdata.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-23T01:24:13.000Z","updated_at":"2024-05-25T15:05:59.000Z","dependencies_parsed_at":"2024-03-21T18:54:55.491Z","dependency_job_id":"b8faca72-146c-488a-985d-63e518bfd9ef","html_url":"https://github.com/influxdata/openapi","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Fopenapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Fopenapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Fopenapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/influxdata%2Fopenapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/influxdata","download_url":"https://codeload.github.com/influxdata/openapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248325348,"owners_count":21084908,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T11:19:19.747Z","updated_at":"2025-04-11T01:32:56.422Z","avatar_url":"https://github.com/influxdata.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Influx API Definitions\n\n[Jump to API contracts.](./contracts)\n\n- [Influx API Definitions](#influx-api-definitions)\n  - [Overview](#overview)\n  - [FAQs](#faqs)\n    - [What is an \"internal\" vs \"external\" API?](#what-is-an-internal-vs-external-api)\n    - [What is a \"private\" vs \"public\" API?](#what-is-a-private-vs-public-api)\n    - [Is the API versioned?](#is-the-api-versioned)\n    - [What is a gateway?](#what-is-a-gateway)\n    - [What is the flow of an external request?](#what-is-the-flow-of-an-external-request)\n    - [What is the flow of an internal request?](#what-is-the-flow-of-an-internal-request)\n    - [Why is the API spec maintained separately from the code?](#why-is-the-api-spec-maintained-separately-from-the-code)\n    - [Other swagger definitions?](#other-swagger-definitions)\n  - [How to use](#how-to-use)\n    - [Prologue](#prologue)\n    - [Example (consumer)](#example-consumer)\n    - [Notes](#notes)\n  - [How to contribute](#how-to-contribute)\n    - [Guidelines](#guidelines)\n    - [Add and update paths and operations](#add-and-update-paths-and-operations)\n    - [Add and update service definitions](#add-and-update-service-definitions)\n    - [What to do when Cloud and OSS diverge](#what-to-do-when-cloud-and-oss-diverge)\n    - [Add tag content or describe a group of paths](#add-tag-content-or-describe-a-group-of-paths)\n\n## Overview\n\nThis repository contains [OpenAPI specifications](https://www.openapis.org/) for InfluxData's various services. It provides a common place for shared API elements that are referenced by more specific API definitions.\n\nThis repository is organized as follows:\n\n```\n.\n├── contracts/              # contains the aggregated openapi definitions; the \"source of truth\"\n|   └── svc/                # contains the aggregated openapi internal api definitions for each individual standalone service\n├── scripts/                # contains various scripts to aid in the generation of the contracts\n└── src/                    # contains the raw openapi definitions\n    ├── cloud/              # contains cloud specific openapi definitions\n    ├── common/             # contains openapi definitions common to oss and cloud\n    |   ├── parameters/     # contains common modular parameter definitions\n    |   ├── paths/          # contains modular path definitions common to oss and cloud\n    |   ├── responses/      # contains common modular response definitions\n    │   ├── schemas/        # contains common modular schema definitions\n    |   ├── _parameters.yml # all parameters common to oss and cloud\n    |   ├── _paths.yml      # all paths common to oss and cloud\n    │   └── _schemas.yml    # all schemas common to oss anc cloud\n    ├── oss/                # contains oss specific openapi definitions\n    ├── svc/                # contains service openapi definitions\n    |   └── [service]/      # contains service specific definitions; similar structure to 'common'\n    ├── cloud-priv.yml      # defines the \"private\" cloud api ('/api/v2private')\n    ├── cloud.yml           # defines the cloud api\n    ├── common.yml          # defines the shared api elements (between cloud and oss)\n    ├── oss.yml             # defines the oss api\n    ├── svc-[service].yml   # defines an individual service api\n    ├── quartz-oem.yml      # defines the oem quartz api\n    └── unity.yml           # defines the unity api\n```\n\nTo learn how to add and update definitions, see [How to contribute](#how-to-contribute).\n\n## FAQs\n\n### What is an \"internal\" vs \"external\" API?\n\n\"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.\n\"External\" API refers to the API that a gateway serves.\n\n### What is a \"private\" vs \"public\" API?\n\n\"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.\n\"Public\" API refers to a documented API used for normal use of the platform.\n\n### Is the API versioned?\n\nSince 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.\n\n### What is a gateway?\n\nGateway refers to the entry point into our platform (whether it be a reverse proxy or some other router).\n\n### What is the flow of an external request?\n\n[client] -\u003e [gateway] -\u003e [service]\n\n- An external `client` makes a request for `/api/v2/thing`.\n- `gateway` finds where to handle requests for `/thing` and forwards the request to that service.\n- `service` then handles that request and responds to the client.\n\n### What is the flow of an internal request?\n\n[service] -\u003e [service]\n\n- A `service` running inside the platform makes a request to another platform `service` at `/thing`.\n- `service` then handles that request and responds to the client (requesting `service`).\n\n### Why is the API spec maintained separately from the code?\n\nAlthough 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:\n\n- Standard location: consumers aren't left wondering where they need to look for the current API contract of a service.\n- 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.\n- Simpler integration: integration of the service into the \"external\" API doesn't require updating the reference path.\n\n### Other swagger definitions?\n\nThe 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.**\n\n## How to use\n\n### Prologue\n\nVarious tools can consume the OpenAPI specification and generate API client *libraries* for different programming languages.\nA client *application* can then import a client library and interact with the API.\nThis repository, specifically the [`contracts`](./contracts/) directory, contains OpenAPI definitions to generate client libraries.\nSimilar to how [Go (golang)](https://go.dev/) 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.\n\nIt 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`.\n\nThese 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.\n\nAs the \"InfluxDB API\" evolves and eventually gets versioned, we can continue to provide complete API definitions in [`ref`](./contracts/ref/), while allowing each sub-service (write, query, tasks, etc.) to evolve on its own.\n\n### Example (consumer)\n\nThe following example generates a `mapsd` client library for golang that consumers can use to interact with the `mapsd` service:\n\n```sh\n# prepare directory for generated library\nmkdir -p /tmp/output\n\n# generate golang library for mapsd (same pattern goes for any service or definition)\ndocker 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/\n```\n\nThe library is then ready for use in an application:\n\n```go\nimport mapsd \"\u003csome-prefix\u003e/mapsd/swagger\"\n\n...\n\n  mapsd.NewAPIClient.GetMapboxToken(context.Background())\n```\n\n### Notes\n\nThere are some limitations to this work.\nInfluxDB UI requires that the definitions it consumes be [oats](https://github.com/influxdata/oats)-compatible and oats-consumable.\nFor 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.\nThis is exemplified in `cloud-priv.yml` and its `servers` key - the main difference between `cloud-priv.yml` and `cloud.yml`.\n\n## How to contribute\n\nTo update and generate contracts, do the following:\n\n1. Clone this repository (`influxdata/openapi`).\n2. If you haven't already, [install and run Docker](https://docs.docker.com/get-docker/).\n3. Review the [guidelines](#guidelines).\n4. Edit [`src`](./src) files.\n5. With Docker running, run `make generate-all` to generate new API contracts.\n6. Commit the result, including the generated `./contracts` files, and create a pull request.\n\n### Guidelines\n\nFollow these guidelines to add and update specifications:\n\n- [Add and update paths and operations](#add-and-update-paths-and-operations)\n- [Add and update service definitions](#add-and-update-service-definitions)\n- [What to do when Cloud and OSS diverge](#what-to-do-when-cloud-and-oss-diverge)\n- [Add tag content or describe a group of paths](#add-tag-content-or-describe-a-group-of-paths)\n\n### Add and update paths and operations\n\nIf you're adding or updating paths and operations (`get`, `post`, etc.), follow our [path template](./docs/templates/pathTemplate.yml) for `summary`, `description`, and `example` elements.\n\n### Add and update service definitions\n\nTo 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.\nThis 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.\nFor more information on how to add a new service API definition, see [src/svc/README](./src/svc/README.md).\n\n### What to do when Cloud and OSS diverge\n\nFor information on what to do when platform APIs drift, see [src/README](./src/README.md).\n\n### Add tag content or describe a group of paths\n\nUse OpenAPI `tags` to group related endpoints (OpenAPI *Paths*).\nDocumentation generators that consume the API can use tags to provide navigation and additional information.\nAPI reference docs\n([OSS](https://docs.influxdata.com/influxdb/latest/api/),\n[Cloud](https://docs.influxdata.com/influxdb/cloud/api/))\nuse the following tag elements and vendor extensions:\n\n- `tag` Tags element: renders endpoint (Path) groups and *trait tags* in navigation menus--for example, **Tasks**.\n- `description` Tag field: describes related Paths and their common features.\n- `x-traitTag: true` Tag field: instead of grouping paths, the tag renders a topical section that contains supplemental information about the API.\n- `x-tagGroups` Root element: groups and sorts `tag` elements for navigation menus--for example, **Data I/O endpoints**.\n\nTo edit these elements, see the platform-specific files:\n\n- `src/[platform]/tags.yml`\n- `src/[platform]/tag-groups.yml`\n\nFor more information, see [influxdata/docs-v2 /api-docs README](https://github.com/influxdata/docs-v2/blob/master/api-docs/README.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfluxdata%2Fopenapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfluxdata%2Fopenapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfluxdata%2Fopenapi/lists"}