{"id":19836711,"url":"https://github.com/rapidapi/create_or_update_rapidapi_listing","last_synced_at":"2025-08-08T20:18:45.192Z","repository":{"id":237082966,"uuid":"626348466","full_name":"RapidAPI/create_or_update_rapidapi_listing","owner":"RapidAPI","description":null,"archived":false,"fork":false,"pushed_at":"2023-04-27T15:27:48.000Z","size":2588,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-07-18T18:47:12.432Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/RapidAPI.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}},"created_at":"2023-04-11T09:36:07.000Z","updated_at":"2023-04-17T10:34:28.000Z","dependencies_parsed_at":"2024-04-29T22:43:51.224Z","dependency_job_id":"463d796b-682a-4174-b694-4db265177bcf","html_url":"https://github.com/RapidAPI/create_or_update_rapidapi_listing","commit_stats":null,"previous_names":["rapidapi/create_or_update_rapidapi_listing"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/RapidAPI/create_or_update_rapidapi_listing","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RapidAPI%2Fcreate_or_update_rapidapi_listing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RapidAPI%2Fcreate_or_update_rapidapi_listing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RapidAPI%2Fcreate_or_update_rapidapi_listing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RapidAPI%2Fcreate_or_update_rapidapi_listing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RapidAPI","download_url":"https://codeload.github.com/RapidAPI/create_or_update_rapidapi_listing/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RapidAPI%2Fcreate_or_update_rapidapi_listing/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269482625,"owners_count":24424404,"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","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-12T12:12:14.715Z","updated_at":"2025-08-08T20:18:45.063Z","avatar_url":"https://github.com/RapidAPI.png","language":"JavaScript","readme":"# Create or update an API listing on RapidAPI Hub\n\nThis is a preview release of a GitHub action designed to make it easy to onboard\nnew APIs onto RapidAPI Hub or Enterprise Hub, or create new versions of existing\nAPIs. It uses the RapidAPI Platform API to upload an OpenAPI spec file and\nreturns the ID of the new API, as well as the name and ID of the newly created\nAPI version.\n\n## Usage\n\nThe action needs an OpenAPI v3.0 spec file in JSON format to exist in the repo. The\nname of this file (or path to it, if it is in a subdirectory), needs to be fed to\nthe action by setting the `spec_path` environment variable.\n\nThe action takes the `info.title` field from the provided OpenAPI spec file as the name\nof the API. It will then search for an existing API listing on the Hub that is owned by\nthe entity with `owner_id` as its ID (see below at [Inputs](#inputs) for mandatory\nvariables).\n\nIf an existing API listing with the same name can be found, it will compare the the\nversion in `info.version` field in the OpenAPI spec file to what is available on the Hub\nand decide - according to configurable policy - what to do with the OpenAPI spec file.\nMore about the possibilities of update [policy](#policy) below.\n\nIf an existing API with the same name cannot be found, a new API listing will be\ncreated. The new API listing will be owned by the owner of the `x-rapidapi-key`.\n\n### Requirements\n\nIf you are a RapidAPI Enterprise Hub user, you need the preview of the GraphQL Platform\nAPI enabled in your Hub. You will need credentials (the `x-rapidapi-key` and\n`x-rapidapi-host` headers) of a user or team that is enabled to use this API, as well as\ntheir owner ID.\n\nNote: if the used `x-rapidapi-key` is owned by a team, you also need to provide\nan `x-rapidapi-identity-key`, which needs to be owned by an **individual user**.\n\n### Example workflow\n\n```yaml\nname: My API Workflow\non: push\njobs:\n    build:\n        runs-on: ubuntu-latest\n        steps:\n            - uses: actions/checkout@master\n            - name: Upload OAS to RapidAPI Hub for processing\n              uses: RapidAPI/create_or_update_rapidapi_listing@v0\n              with:\n                  spec_path: openapi.json\n                  owner_id: 12345678\n                  graphql_url: https://platform-graphql.p.rapidapi.com/\n                  x_rapidapi_key: a-very-long-api-key\n                  x_rapidapi_identity_key: another-very-long-api-key\n                  x_rapidapi_graphql_host: platform-graphql.yourhub.rapidapi.com\n```\n\nUsually, you would set those variables (`owner_id` etc.) as Action secrets for your\nrepo. In that case, you would refer to them as e.g. `${{ secrets.OWNER_ID }}`, assuming\nyou named the secret storing your owner ID `OWNER_ID`.\n\n### Inputs\n\n| Input                     | Description                                                                                                                        | Required |\n| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------- |\n| `spec_path`               | Path to the OpenAPI spec file in JSON format                                                                                       | True     |\n| `owner_id`                | Id of the team / user owning the existing API, or team / user to own the new API | True |\n| `x_rapidapi_key`          | API key for the user / the team that will own this API on the Hub                                                                  | True     |\n| `x_rapidapi_identity_key` | API key for the user that executes the action. If `x_rapidapi_key` is owned by a team, this field is required and needs to be belong to an individual user. | False     |\n| `x_rapidapi_graphql_host` | GraphQL platform API host for the user / the team that will own this API on the Hub (e.g. `graphql-platform.yourhub.rapidapi.com`) | True     |\n| `graphql_url`             | The URL to the GraphQL Platform API, defaults to `https://graphql-platform.p.rapidapi.com/` (mind the slash!)                      | True     |\n\n### Outputs\n\n| Output             | Description                                                                 |\n| ------------------ | --------------------------------------------------------------------------- |\n| `api_id`           | The ID of the newly created or updated API on the RapidAPI Hub              |\n| `api_version_name` | The name (e.g. v0.2.0) of the newly created API version on the RapidAPI Hub |\n| `api_version_id`   | The ID of the newly created API version on the RapidAPI Hub                 |\n\n### Using outputs\n\nThe outputs of this action (`api_id` and `api_version_id`) can be used as input\nto subsequent actions:\n\n```yaml\nsteps:\n- uses: actions/checkout@master\n- name: Upload OAS to RapidAPI Hub for processing\n  id: rapidapi-upload\n  uses: RapidAPI/creat_or_update_rapidapi@v0\n  with:\n    spec_path: openapi.json\n    [...]\n\n- name: Check outputs\n    run: |\n    echo \"New API ID - ${{ steps.rapidapi-upload.outputs.api_id }}\"\n    echo \"New API Version ID - ${{ steps.rapidapi-upload.outputs.api_version_id }}\"\n```\n\n## Policy\nThe GitHub Action allows you to set a policy for updating / creating new API versions on\nthe RapidAPI Hub. This functionality is still in flux, so make sure to read the rules\nbelow and create issues for any bugs you find!\n\nBy default, the following rules will apply:\n\n| Key                     | Default value | Decription                                            |\n|-------------------------|---------------|-------------------------------------------------------|\n| create_as               | \"active\"      | New API versions are to be created as active, draft or deprecated |\n| allow_update_existing   | false         | Whether to re-upload if API version already exists\n| allow_update_deprecated | true          | Whether to allow updates to API versions marked deprecated (not implemented yet)\n| major.update_policy     | \"create\"      | What to do if the new OpenAPI spec contains a new major version\n| major.allow_older       | true          | Allow creation of major versions that are older than the ones that already exist\n| major.auto_current      | false         | Set new major versions as 'current' automatically?\n| minor.update_policy     | \"update\"      | What to do if the new OpenAPI spec contains a new minor version\n| minor.allow_older       | true          | Allow creation of minor versions that are older than the ones that already exist\n| minor.auto_current      | false         | Set new minor versions as 'current' automatically?\n| patch.update_policy     | \"update\"      | What to do if the new OPenAPI spec contains a new patch version\n| patch.allow_older       | true          | Allow creation of patch versions that are older than the ones that already exist\n| patch.auto_current      | false         | Set new patch versions as 'current'\nautomatically?\n\nAPI versions on the Hub can be in three states: active (visible on Hub), draft (visibile\non Hub to API owner) and deprecated (visibile on Hub to owner and entities that have\npreviously subscribed to it). This settings configures what the default for new versions\nwill be. Active and draft are the most likely to be used. Use 'deprecated' only if e.g.\nthe whole API is deprecated but still maintained for some time.\n\n#### Generic policy\n\nThe `allow_update_existing` key either allows or prohibits uploading e.g. a v1.0.1 into\nan existing API version with that exact version number. Can be useful if you regularly\nuse the same version number. But your shouldn't really do this, so it's false by\ndefault.\n\nThe `allow_update_deprecated` key either allows or prohibits updating API versions that\nare marked as deprecated. Sometimes, we might want this (e.g. with a critical bug in an\nAPI version that is marked as deprecated). This will be allowed by default, but at this\nmoment, this functionality is not implemented yet.\n\n#### Version specific policy\n\nNext are three blocks that define creation policy for major, minor and patch versions of\nAPIs. Each block has an `update_policy` key, an `allow_older` key and an `auto_current`\nkey.\n\nThe `update_policy` key can be 'create', 'update' or 'forbid'. If set as `create`, every\ntime the version number in the spec increases and this Action runs, a new API version\nwill be created on the Hub.\n\nIf set to `update`, every time the version number in the spec increases and this Action\nruns, the closest lower version of this API will be updated to the version number that\nis defined in the spec. E.g. if a v2.0.0. is available on the Hub already, and the new\nspec contains v2.0.1, the existing v2.0.0 will be updated to be v2.0.1 and no new\nversion will be created.\n\nIf set to `forbid`, it will become forbidden to e.g. create new major versions of an\nAPI. This can be useful for when you want to have a git branch to maintain a specific\nreleased API version, and only every created patch versions from that branch. This is\nnot a fool-proof method of preventing creation of unintended API versions from a branch.\nIt will just prevent to most obvious mistakes.\n\nThe `allow_older` setting allows or prohibits the creation of APIs with a lower version\nnumber than already exist. E.g. if v1.5.4 exists on the Hub, and this settings is false\nfor patch versions, uploading a spec with v1.5.2 in it will result in an error.\n\nFinally, `auto_current` defines whether or not newly created versions will be marked as\ncurrent (i.e. the default on the Hub) automatically. Default is false, some use cases\nmight benefit from this, like having a git branch to maintain v1.1.x, and having set\n`update_policy` for patch to `create`. Every time you bump the version in your spec, the\nAction will create a new version on the Hub that is both active and current.\n\n#### Config file format\n\nConfiguration files are in toml format, and can be added per branch. The need to follow\nthis naming convention: `rapidConfig.$BRANCH.toml`, where `$BRANCH` is the name of the\ngit branch the configuration file is for, e.g. ` main`. If you want to have a single\nconfiguration file for all branches, call it `rapidConfig.default.toml`.\n\nThe format of the config file is as follows (these are the default values:\n```toml\n[general]\ncreate_as = \"active\"\nallow_update_existing = false\nallow_update_deprecated = true\n\n[major]\nupdate_policy = \"create\"\nallow_older = true\nauto_current = false\n\n[minor]\nupdate_policy = \"update\"\nallow_older = true\nauto_current = false\n\n[patch]\nupdate_policy = \"update\"\nallow_older = true\nauto_current = false\n```\n\n## Limitations\n\n- You can only use this Action with APIs you own, either through personal or team\n  credentials.\n- The `allow_update_deprecated` configuration file key isn't implemented yet.\n- There is no check to verify whether the `owner_id`, `x-rapidapi-identity-key` and the\n  `x-rapidapi-key` belong together.\n- There is no check whether an `x-rapidapi-identity-key` is required (in other words:\n  whether or not the `x-rapidapi-key` belongs to a team).\n- There is no support for `on-behalf-of` (which is a limitation of the GraphQL PAPI at\n  the moment).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapidapi%2Fcreate_or_update_rapidapi_listing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frapidapi%2Fcreate_or_update_rapidapi_listing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapidapi%2Fcreate_or_update_rapidapi_listing/lists"}