[Pijukatel]

Summary

Autogenerated OpenAPI fixes suggestions based on validation errors generated from running API integration tests with OpenAPI validator turned on.

This round used the API clients as the request generator: the JavaScript client's unit and integration tests ran through a request-only OpenAPI validator (apify/apify-client-js#1175), and the Python client was driven through the same validator locally. Only requests were validated.

Error log: https://github.com/apify/apify-client-js/actions/runs/40522703825 (warning annotations of the Unit tests and Integration tests jobs)

apify-core version: https://github.com/apify/apify-core/tree/8440e7910c359526f013ea7b42394e386ecccc95

Stop reason: No new fixes possible. Every request-side error the clients produced is either fixed here, already fixed on master by #3118 (the /v2/users/{userId}/limits and /v2/users/{userId}/usage/monthly paths), a known validator false positive, or out of scope (see below).

Detailed changes description

Error fixes

Actor build log: raw query parameter missing

• Files: apify-api/openapi/components/objects/logs/log.yaml:86
• Error: Request OpenAPI validation error GET /v2/actor-builds/{buildId}/log?raw=false: Unknown query parameter 'raw'
• Root cause: The build log operation referenced only the stream and download parameters, while the run log and the generic log operations also reference raw. The API handles the build log by rewriting the request to /v2/logs/{buildId} with the original query string, so raw is accepted there, and both the JavaScript and the Python API clients send it. Verified against the live API: raw and download have the same effect on /v2/actor-builds/{buildId}/log as on /v2/logs/{buildId}.
• Reference: https://github.com/apify/apify-core/tree/8440e7910c359526f013ea7b42394e386ecccc95/src/api/src/routes/actor_builds/build_log.ts#L23

Key-value store record: body restricted to a JSON object

• Files: apify-api/openapi/components/schemas/key-value-stores/PutRecordRequest.yaml:5
• Error: Request OpenAPI validation error PUT /v2/key-value-stores/{storeId}/records/{recordKey}: /body: must be object
• Root cause: PutRecordRequest restricted the application/json body to an object, but the API streams whatever body arrives into the record under the given content type, so a JSON array, string, or number is a valid record. The API clients send such values as JSON, and the API's own integration test stores a plain string. The schema now accepts any JSON value, as the */* media type already does.
• Reference: https://github.com/apify/apify-core/tree/8440e7910c359526f013ea7b42394e386ecccc95/src/api/src/routes/key_value_stores/record.ts#L141, https://github.com/apify/apify-core/tree/8440e7910c359526f013ea7b42394e386ecccc95/tests/integration/tests/key_value_stores/key_value_store.record.js#L52

Refactoring

None.

Unfixed errors

False positives

Space encoded as + in a query value

• Error: Request OpenAPI validation error GET /v2/store?search=web+scraper: Parameter 'search' must be url encoded. Its value may not contain reserved characters.
• Root cause: express-openapi-validator treats + as a reserved character, but + for a space is the standard form encoding of a query string and the API decodes it into the plain search string it validates. Nothing to change in the specification.
• Reference: https://github.com/apify/apify-core/tree/8440e7910c359526f013ea7b42394e386ecccc95/src/api/src/routes/store/search.ts#L543

Upper-case Content-Encoding value

• Error: Request OpenAPI validation error PUT /v2/key-value-stores/{storeId}/records/{recordKey}: /headers/content-encoding: must be equal to one of the allowed values: br, gzip, deflate, identity
• Root cause: The request sent Content-Encoding: IDENTITY. Content codings are case-insensitive per RFC 9110, and the validator compares the enum case-sensitively. The specification lists the canonical lower-case values and stays as it is.
• Reference: https://github.com/apify/apify-core/tree/8440e7910c359526f013ea7b42394e386ecccc95/src/api/src/routes/key_value_stores/record.ts#L101

Potential API bugs

HTML record encoding check is case-sensitive

• Error: Request OpenAPI validation error PUT /v2/key-value-stores/{storeId}/records/{recordKey}: /headers/content-encoding: must be equal to one of the allowed values: br, gzip, deflate, identity
• Root cause: For HTML records the API rejects any Content-Encoding not in its supported list, comparing the header value case-sensitively, so IDENTITY on an HTML record is refused although content codings are case-insensitive per RFC 9110. Not a specification problem.
• Reference: https://github.com/apify/apify-core/tree/8440e7910c359526f013ea7b42394e386ecccc95/src/api/src/routes/key_value_stores/record.ts#L114

Out of scope errors

Store pricingModel value FLAT_PRICE_PER_MONTH

• Error: Request OpenAPI validation error GET /v2/store?limit=10&pricingModel=FLAT_PRICE_PER_MONTH: must be equal to one of the allowed values: FREE, PRICE_PER_DATASET_ITEM, PAY_PER_EVENT
• Root cause: The API still accepts the value, but it was removed from the specification on purpose because the pricing model is being deprecated. Left as it is.

Webhook created without its required fields

• Error: Request OpenAPI validation error POST /v2/webhooks: /body/eventTypes: must have required property 'eventTypes' (also condition and requestUrl)
• Root cause: A client unit test deliberately posts a placeholder body to a mock server. The specification and the API both require the three fields, so the specification is correct and the request is intentionally incomplete.

Issues

Partially implements: #2286

🤖 Generated with Claude Code

[apify-service-account]

✅ Preview for this PR (commit f4aaade9) is ready at https://pr-3128.preview.docs.apify.com (see action run).

[apify-service-account]

API behavior and specification alignment: Aligned.

Reviewed commit: f4aaade