{"id":26558092,"url":"https://github.com/wso2/api-specs","last_synced_at":"2025-07-14T18:38:12.109Z","repository":{"id":282407863,"uuid":"948492647","full_name":"wso2/api-specs","owner":"wso2","description":"This repository contains API specifications (openAPI, GraphQL, etc.) for public APIs.","archived":false,"fork":false,"pushed_at":"2025-05-26T05:16:12.000Z","size":11794,"stargazers_count":2,"open_issues_count":1,"forks_count":4,"subscribers_count":78,"default_branch":"main","last_synced_at":"2025-05-26T06:30:17.842Z","etag":null,"topics":["api","contracts","openapi","specifications"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wso2.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-14T12:40:10.000Z","updated_at":"2025-05-26T05:16:16.000Z","dependencies_parsed_at":"2025-03-14T13:37:38.844Z","dependency_job_id":"64a3f799-d8ca-4172-960a-07085a352f87","html_url":"https://github.com/wso2/api-specs","commit_stats":null,"previous_names":["wso2/api-specifications"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/wso2/api-specs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wso2%2Fapi-specs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wso2%2Fapi-specs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wso2%2Fapi-specs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wso2%2Fapi-specs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wso2","download_url":"https://codeload.github.com/wso2/api-specs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wso2%2Fapi-specs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265333304,"owners_count":23748775,"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":["api","contracts","openapi","specifications"],"created_at":"2025-03-22T12:22:12.908Z","updated_at":"2025-07-14T18:38:12.102Z","avatar_url":"https://github.com/wso2.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# WSO2 API Specifications Repository\n\nThis repository contains API contracts for various vendors and APIs in a standardized format. The goal of this repository is to provide a centralized location for API contracts that can be used for client/connector generation, testing, and documentation.\n\n## Description\n\n### Branching Strategy\n\nThe repository will contain two primary branches:\n\n- `main`\n- `incubator`\n\n#### The `main` Branch\n\nThe `main` branch contains the official API contracts that are stable and verified.\n\n#### The `incubator` Branch\n\nThe `incubator` branch contains API contracts that are under development, experimental, or non-official. An API contract can be added to this branch if it is not yet stable or verified. Once the API contract is stable and verified, it can be graduated to the `main` branch.\n\n### Repository Structure\n\nThis centralized repository is for storing API contracts in a standardized format such as OpenAPI, GraphQL SDL, AsyncAPI, or other relevant specifications.\n\nThe repository structure would be organized as follows:\n\n```shell\n\napi-specs/\n├── asyncapi/\n├── graphql/\n└── openapi/\n```\n\n\u003e **Note:** Additional directories can be added in the future for other API contract specifications.\n\nThe repository root contains subdirectories for each contract type, such as `openapi`, `graphql`, and `asyncapi`. Each subdirectory contains API contracts for different vendors, APIs, and versions.\n\n#### OpenAPI Contracts Directory Structure\n\nThe following is the directory structure for OpenAPI specifications:\n\n1. Each vendor has their own directory. (E.g.: `openapi/google`, `openapi/hubspot`, etc.)\n2. Within the vendor directory, each API has its own directory. (E.g.: `openapi/google/docs`, `openapi/hubspot/crm.associations`, etc.)\n   \u003e **Note:** If the vendor and the API name are the same, the directory names would be the same. (E.g.: `openapi/asana/asana`, `openapi/dayforce/dayforce`, etc.)\n3. If the API is categorized hierarchically, the API directory would be named with the hierarchy, separated with a dot (`.`). (E.g.: `openapi/hubspot/crm.associations`, `openapi/hubspot/automation.actions`, etc.)\n4. Within the API directory, another directory would be created for each version of the API. (E.g.: `openapi/google/calendar/v3`, `openapi/hubspot/automation.actions/v4`, etc.)\n5. Apart from the OpenAPI spec version directory, each API directory contains an `icon.png` file that contains the logo of the API.\n6. Inside the API version directory, the OpenAPI spec file would be named as `openapi.yaml`.\n    \u003e **Note:** If an API contract is in the `JSON` format, it should be converted to `YAML` format before committing to the repository.\n7. The relevant icon for the API would be placed in the API directory as `icon.png`.\n8. A `.metadata.json` file would be placed in the API version directory to store metadata such as the API name, version, vendor, and other relevant information.\n\n##### OpenAPI Metadata File Structure\n\nThe `.metadata.json` file would contain the following information:\n\n- `name`: The human-readable name of the API.\n- `baseUrl`: The base URL of the API. This is added in metadata to easily identify the base URL of the API without parsing the OpenAPI spec.\n- `documentationUrl`: The URL to the API documentation, if available.\n- `description`: A brief description of the API.\n- `tags`: An array of tags that are relevant to the API.\n\n```json\n{\n    \"name\": \"Google Docs API\",\n    \"baseUrl\": \"https://docs.googleapis.com\",\n    \"documentationUrl\": \"https://developers.google.com/docs\",\n    \"description\": \"API Description\",\n    \"tags\": [\"tag1\", \"tag2\"]\n}\n```\n\n###### Example: OpenAPI Contracts Directory Structure\n\n```text\napi-specs/\n└── openapi\n    ├── asana\n    │   └── asana\n    │       ├── 1.0\n    │       │   └── openapi.yaml\n    │       └── icon.png\n    ├── candid\n    │   ├── charityCheckPdf\n    │   │   ├── 1.0\n    │   │   │   └── openapi.yaml\n    │   │   └── icon.png\n    │   ├── essentials\n    │   │   ├── 1.0\n    │   │   │   └── openapi.yaml\n    │   │   └── icon.png\n    │   └── premier\n    │       ├── 1.0\n    │       │   └── openapi.yaml\n    │       └── icon.png\n    ├── dayforce\n    │   └── dayforce\n    │       └── v1\n    │           └── openapi.yaml\n    ├── discord\n    │   └── discord\n    │       ├── 10\n    │       │   └── openapi.yaml\n    │       └── icon.png\n    ├── docusign\n    │   ├── admin\n    │   │   ├── icon.png\n    │   │   └── v2.1\n    │   │       └── openapi.yaml\n    │   ├── click\n    │   │   ├── icon.png\n    │   │   └── v1\n    │   │       └── openapi.yaml\n    │   └── esign\n    │       ├── icon.png\n    │       └── v2.1\n    │           └── openapi.yaml\n```\n\n#### GraphQL Contracts Directory Structure\n\nThe following is the directory structure for GraphQL specifications:\n\n1. Each vendor has their own directory. (E.g.: `graphql/github`, `graphql/shopify`, etc.).\n2. Within each vendor directory, each API has its own directory. (E.g.: `graphql/github/github`, `graphql/shopify/admin`, etc.).\n    \u003e **Note:** If the vendor and the API name are the same, the directory names would be the same. (E.g.: `graphql/github/github`.)\n3. Each API directory will contain a `schema.graphql` file that contains the GraphQL schema.\n    \u003e **Note:** Since GraphQL APIs do not have versions, the schema file would be placed directly under the vendor directory.\n4. The directory would also contain an `icon.png` file that contains the logo of the API.\n5. This directory would also contain a `.metadata.json` file to store metadata.\n\n##### GraphQL Metadata File Structure\n\nThe `.metadata.json` file would contain the following information:\n\n- `name`: The human-readable name of the API.\n- `description`: A brief description of the API.\n- `endpoint`: The endpoint URL of the API.\n- `documentationUrl`: The URL to the API documentation, if available.\n- `tags`: An array of tags that are relevant to the API.\n\n```json\n{\n    \"name\": \"GitHub GraphQL API\",\n    \"description\": \"Access GitHub data using GraphQL. Query repositories, issues, users, and more.\",\n    \"endpoint\": \"https://api.github.com/graphql\",\n    \"documentationUrl\": \"https://docs.github.com/en/graphql\",\n    \"tags\": [\"developer\", \"github\"],\n}\n```\n\n###### Example: GraphQL Contracts Directory Structure\n\n```text\napi-specs/\n└── graphql\n    └── github\n        └── github\n            ├── .metadata.json\n            ├── icon.png\n            └── schema.graphql\n```\n\n#### AsyncAPI Contracts Directory Structure\n\nThe AsyncAPI directory structure would be similar to the [OpenAPI directory structure](#openapi-contracts-directory-structure). The only difference is that the AsyncAPI spec file would be named as `asyncapi.yaml`.\n\n###### Example: AsyncAPI Contracts Directory Structure\n\n```text\napi-specs/\n└── asyncapi\n    └── slack\n        └── events\n            ├── 1.0.0\n            │   └── asyncapi.yaml\n            └── icon.png\n```\n\n##### AsyncAPI Metadata File Structure\n\nThe `.metadata.json` file would contain the following information:\n\n- `name`: The human-readable name of the API.\n- `description`: A brief description of the API.\n- `protocol`: The protocol used by the API.\n- `documentationUrl`: The URL to the API documentation, if available.\n- `tags`: An array of tags that are relevant to the API.\n\n```json\n{\n    \"name\": \"Slack Events API\",\n    \"description\": \"AsyncAPI contract for Slack Events API.\",\n    \"protocol\": \"WebSocket\",\n    \"documentationUrl\": \"https://api.slack.com/apis/events-api\",\n    \"tags\": [\"slack\", \"events\"],\n}\n```\n\n### API Contract Validation\n\nAn API contract is considered verified if _one of the following conditions_ is met:\n\n- The specification is from the official source.\n- The specification is used to generate and publish a connector/client and is tested and verified.\n\nThe [`main`](https://github.com/wso2/api-specs/tree/main) branch contains only valid API contracts. The [`incubator`](https://github.com/wso2/api-specs/tree/incubator) branch may contain contracts that are not yet verified.\n\n### API Contract Graduation\n\nIf an API contract is not from the official source, it can be graduated to the `main` branch after the following conditions are met:\n\n- The API contract is used to generate a connector/client.\n- The generated connector/client is tested and verified against the live API.\n\nWhen graduating an API contract, the following steps should be followed:\n\n1. Validate whether the API contract is in the correct format.\n    * OpenAPI: The OpenAPI spec should be in YAML format and should follow the OpenAPI specification.\n    * GraphQL: The GraphQL schema should be in SDL format and should follow the GraphQL specification.\n    * AsyncAPI: The AsyncAPI spec should be in YAML format and should follow the AsyncAPI specification.\n2. Add a valid `.metadata.json` file to the API version directory.\n3. Add the relevant `icon.png` file to the API directory.\n4. Send a pull request to the `main` branch.\n\n## Reporting Issues\n\nIf you find any issues with the exiting API specifications, please raise an issue in the [Issues](https://github.com/wso2/api-specs/issues) section of this repository. If you have a new API specification that you would like to contribute, please send a pull request, following the above conventions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwso2%2Fapi-specs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwso2%2Fapi-specs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwso2%2Fapi-specs/lists"}