{"id":18710659,"url":"https://github.com/apify/openapi","last_synced_at":"2025-04-12T12:30:45.217Z","repository":{"id":234167247,"uuid":"774359787","full_name":"apify/openapi","owner":"apify","description":"An OpenAPI specification for the Apify API.","archived":false,"fork":false,"pushed_at":"2024-10-29T08:45:00.000Z","size":872,"stargazers_count":2,"open_issues_count":20,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-29T09:57:03.766Z","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/apify.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":"2024-03-19T12:15:30.000Z","updated_at":"2024-10-29T08:45:03.000Z","dependencies_parsed_at":"2024-05-31T16:04:21.408Z","dependency_job_id":"a33ee213-7776-4db2-af3a-71442d85c651","html_url":"https://github.com/apify/openapi","commit_stats":null,"previous_names":["apify/openapi"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fopenapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fopenapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fopenapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fopenapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apify","download_url":"https://codeload.github.com/apify/openapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223515318,"owners_count":17158353,"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-07T12:35:11.680Z","updated_at":"2025-04-12T12:30:45.191Z","avatar_url":"https://github.com/apify.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DEPRECATED!\n\nThis repository is no longer used, the specification is now moved to the apify-docs repository:\n\nhttps://github.com/apify/apify-docs/tree/master/apify-api\n\n# Apify API v2 OpenAPI Definition\n\n## Working on OpenAPI Definition\n\n### Install\n\n1. Install [Node JS](https://nodejs.org/).\n2. Clone this repo and run `npm install` in the repo root.\n3. Install Schemahtesis for contract testing against staging: `python -m pip install schemathesis`\n4. `cp .env.example .env`, and insert the `APIFY_STAGING_TOKEN`\n\n### Usage\n\n#### `npm start`\nStarts the reference docs preview server.\n\n#### `npm run build`\nBundles the definition to the dist folder.\n\n#### `npm test`\nValidates the definition.\n\n## Contribution Guide\n\n**TL;DR**: Add your schema to `openapi/components/schemas` and your path to `openapi/paths` and reference them in `openapi.yaml`. \nOpen pull request into `main` branch.\n\nNOTE: The `.redocly.yaml` controls settings for various\ntools including the lint tool and the reference\ndocs engine.  Open it to find examples and\n[read the docs](https://redoc.ly/docs/cli/configuration/)\nfor more information.\n\n### Schemas\n\n#### Adding Schemas\n\n1. Navigate to the `openapi/components/schemas` folder.\n2. Add a file named as you wish to name the schema.\n3. Define the schema.\n4. Refer to the schema using the `$ref` (see example below).\n\n##### Example Schema\nThis is a very simple schema example:\n```yaml\ntype: string\ndescription: The resource ID. Defaults to UUID v4\nmaxLength: 50\nexample: 4f6cf35x-2c4y-483z-a0a9-158621f77a21\n```\nThis is a more complex schema example:\n```yaml\ntype: object\nproperties:\n  id:\n    description: The customer identifier string\n    readOnly: true\n    allOf:\n      - $ref: ./ResourceId.yaml\n  websiteId:\n    description: The website's ID\n    allOf:\n      - $ref: ./ResourceId.yaml\n  paymentToken:\n    type: string\n    writeOnly: true\n    description: |\n      A write-only payment token; if supplied, it will be converted into a\n      payment instrument and be set as the `defaultPaymentInstrument`. The\n      value of this property will override the `defaultPaymentInstrument`\n      in the case that both are supplied. The token may only be used once\n      before it is expired.\n  defaultPaymentInstrument:\n    $ref: ./PaymentInstrument.yaml\n  createdTime:\n    description: The customer created time\n    allOf:\n      - $ref: ./ServerTimestamp.yaml\n  updatedTime:\n    description: The customer updated time\n    allOf:\n      - $ref: ./ServerTimestamp.yaml\n  tags:\n    description: A list of customer's tags\n    readOnly: true\n    type: array\n    items:\n      $ref: ./Tags/Tag.yaml\n  revision:\n    description: \u003e\n      The number of times the customer data has been modified.\n\n      The revision is useful when analyzing webhook data to determine if the\n      change takes precedence over the current representation.\n    type: integer\n    readOnly: true\n  _links:\n    type: array\n    description: The links related to resource\n    readOnly: true\n    minItems: 3\n    items:\n      anyOf:\n        - $ref: ./Links/SelfLink.yaml\n        - $ref: ./Links/NotesLink.yaml\n        - $ref: ./Links/DefaultPaymentInstrumentLink.yaml\n        - $ref: ./Links/LeadSourceLink.yaml\n        - $ref: ./Links/WebsiteLink.yaml\n  _embedded:\n    type: array\n    description: \u003e-\n      Any embedded objects available that are requested by the `expand`\n      querystring parameter.\n    readOnly: true\n    minItems: 1\n    items:\n      anyOf:\n        - $ref: ./Embeds/LeadSourceEmbed.yaml\n\n```\n\n\n\n##### Using the `$ref`\n\nNotice in the complex example above the schema definition itself has `$ref` links to other schemas defined.\n\nHere is a small excerpt with an example:\n\n```yaml\ndefaultPaymentInstrument:\n  $ref: ./PaymentInstrument.yaml\n```\n\nThe value of the `$ref` is the path to the other schema definition.\n\nYou may use `$ref`s to compose schema from other existing schema to avoid duplication.\n\nYou will use `$ref`s to reference schema from your path definitions.\n\n#### Editing Schemas\n\n1. Navigate to the `openapi/components/schemas` folder.\n2. Open the file you wish to edit.\n3. Edit.\n\n### Paths\n\n#### Adding a Path\n\n1. Navigate to the `openapi/paths` folder.\n2. Add a new YAML file named like your URL endpoint except replacing `/` with `@` into folder named by the collection (example `request-queues`) \n3. Put path parameters into curly braces like `{example}`.\n4. Add the path and a ref to it inside of your `openapi.yaml` file inside of the `openapi` folder.\n\nExample addition to the `openapi.yaml` file:\n```yaml\n'/requests-queues':\n  $ref: './paths/request-queues/request-queues.yaml'\n'/requests-queues/{queueId}':\n  $ref: './paths/request-queues/request-queues@{queueId}.yaml'\n```\n\nHere is an example of a YAML file named `request-queues@{queueId}.yaml` in the `paths/request-queues` folder:\n\n```yaml\nget:\n  tags:\n    - Request Queues\n  summary: Get a Request Queue\n  operationId: requestQueues_get\n  description: |\n    You can have a markdown description here.\n  parameters:\n  responses:\n    '200':\n    '401':\n  x-code-samples:\n    - lang: PHP\n      source:\n        $ref: ../code_samples/PHP/customers/get.php\n```\nHere is an example of a YAML file named `request-queues.yaml` in the `paths/request-queues` folder:\n    \n```yaml\npost:\n  tags:\n    - Request Queues\n  summary: Create a request queue\n  operationId: requestQueue_post\n  description: Another markdown description here.\n  requestBody:\n  responses:\n    '201':\n      description: ''\n      content:\n        application/json:\n          schema:\n            allOf:\n              - $ref: ../../components/schemas/request-queues/CreateRequestQueueResponse.yaml\n  x-code-samples:\n    - lang: PHP\n      source:\n        $ref: ../code_samples/PHP/customers/post.php\n```\n\nYou'll see extensive usage of `$ref`s in this example to different types of components including schemas.\n\nYou'll also notice `$ref`s to code samples.\n\n#### Operation ID\n\nThe `operationId` is a unique identifier of the operation. It is used by the Redocly API Reference to generate code samples and link them to the operation from other parts of the documentation.\n\nThere is a format for the `operationId`:\n\n- The ID is generated from the path structure and the HTTP method.\n- The object names should be in camelCase.\n- If there is `{id}` in the path, the previous part of the path should be singular, otherwise plural.\n- The divider between the object name and the action should be `_`.\n- The action should be last in the `operationId` defined by the method name in lowercase.\n\nExamples:\n- `/requests-queues` Method: GET -\u003e `requestQueues_get`\n- `/requests-queues` Method: POST -\u003e`requestQueues_post`\n- `/requests-queues/{queueId}` Method: PUT -\u003e `requestQueue_put`\n- `/acts/{actorId}/runs` Method: POST -\u003e `act_runs_post`\n- `/acts/{actorId}/runs` Method: GET -\u003e `act_runs_get`\n- `/acts/{actorId}/versions/{versionNumber}/env-vars/{envVarName}` Method: GET -\u003e `act_version_envVar_get`\n\n### Code samples\nNOTE: We do not use code samples in the OpenAPI definition for now. \nWe can use them in the future to generate code samples for the reference docs.\n\n1. Navigate to the `openapi/code_samples` folder.\n2. Navigate to the `\u003clanguage\u003e` (e.g. PHP) sub-folder.\n3. Navigate to the `path` folder, and add ref to the code sample.\n\nYou can add languages by adding new folders at the appropriate path level.\n\nMore details inside the `code_samples` folder README.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapify%2Fopenapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapify%2Fopenapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapify%2Fopenapi/lists"}