overlay: 1.0.0 info: title: API Evangelist enhancements for the GZW Data API version: 1.0.0 x-provenance: generated: '2026-09-03' method: generated source: openapi/_original/gzw-data-openapi.json (verbatim from https://gzw-data.dev/api/v1/spec, implementation 4.2.0, re-fetched 2026-09-03) note: >- Non-destructive Overlay 1.0.0 capturing enhancements API Evangelist derived from the provider's own docs and from live probes. REVISED 2026-09-03 for implementation 4.2.0: the provider has since added the responses this overlay previously had to describe from the outside — all 362 operations now declare 200/400/404/429 against shared $ref schemas, and 176 declare their path parameters. What the contract STILL omits, and what this overlay therefore still carries, is: operationIds, operation descriptions, tags, contact/licence/terms metadata, an explicit empty security requirement, and every QUERY parameter (page, per_page, all, search, sort, field equality, and the four search-route parameters dataset/fields/fuzzy/limit) — zero query parameters are declared anywhere in 4.2.0. It does NOT invent endpoint behaviour and it does not modify openapi/_original/gzw-data-openapi.json. extends: openapi/_original/gzw-data-openapi.json actions: - target: $.info description: Add contact, licence, terms and a fuller description sourced from the provider's own pages. update: description: >- Free, fan-made, read-only REST API for Gray Zone Warfare game data — 85+ auto-discovered datasets covering weapons, ammo, armor, tasks/missions, gear, loot, containers and vendors, scraped from the community GZW Fandom Wiki. No API key and no account required. Best-effort rate limit of 100 requests per minute per IP. Not affiliated with or endorsed by the game's publisher. termsOfService: https://gzw-data.dev/terms-of-service/ contact: name: ZoniBoy00 url: https://github.com/ZoniBoy00/gzw-data/issues license: name: MIT url: https://github.com/ZoniBoy00/gzw-data/blob/main/LICENSE x-privacy-policy: https://gzw-data.dev/privacy-policy/ x-data-source: https://gray-zone-warfare.fandom.com/wiki/Gray_Zone_Warfare_Wiki - target: $ description: Declare an explicitly empty security requirement — the API is public and unauthenticated. update: security: [] x-authentication: none x-api-key-required: false - target: $.servers description: Note the legacy compatibility prefix alongside the versioned base. update: - url: https://gzw-data.dev description: Production. Use the /api/v1 prefix for new integrations; the unversioned /api prefix is compatibility-only. - target: $.info description: Record the runtime conventions the docs publish but the contract omits. update: x-rate-limit: limit: 100 window: 1 minute scope: per-ip enforcement: best-effort (per warm serverless instance, not a strict global quota) headers: [X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After] exhausted_status: 429 x-caching: data_routes: 'Cache-Control: public, max-age=300' validators: weak ETag x-cors: allow_origin: '*' x-contract-version-observed: implementation_version: 4.2.0 observed: '2026-09-03' previous: 4.0.0 observed 2026-08-26 responses_declared: true query_parameters_declared: false x-search-parameters: - name: q description: The search query, on GET /api/v1/search. - name: dataset description: Limit the search to one or more comma-separated datasets. - name: fields description: Search only the named comma-separated fields. - name: fuzzy description: fuzzy=true allows small spelling and punctuation differences. - name: limit description: Matches per dataset; documented maximum 50. x-query-parameters: - name: page description: 1-based page number. Default 1. - name: per_page description: Page size. Default 50, documented cap 500. - name: all description: all=true returns every filtered record without pagination. - name: search description: Full-text search across the record fields of the dataset. - name: sort description: 'Sort by a field, syntax field:asc or field:desc.' - name: '{field}' description: Filter by equality on any string field, e.g. ?type=Keycard. x-response-envelope: fields: [data, count, page, perPage, total, totalPages, source, timestamp] note: Unpaginated responses omit the pagination fields and keep data, count, source, timestamp. - target: $.components.schemas.ApiErrorResponse description: Document the additional envelope members observed on live error responses. update: x-observed-members: dataVersion: ISO timestamp of the scrape the response was served from x-error-codes: - code: ENDPOINT_NOT_FOUND status: 404 note: Body carries an `available` array of the dataset names that DO exist. - code: RECORD_NOT_FOUND status: 404 note: Body carries `dataset`, `id` and a `docs` pointer to /api/v1/spec. - code: DATASET_NOT_FOUND status: 404 x-not-rfc9457: >- Served as application/json with a vendor {error:{code,message},source,timestamp} envelope; not application/problem+json. - target: $.paths description: Record the live, documented routes that are ABSENT from the published contract. update: x-undocumented-in-spec: note: >- These routes are documented in the provider's own README, docs and llms.txt AND return 200 live, but no path item for them exists in the published OpenAPI. NARROWED 2026-09-03: /api/v1/search was on this list against 4.0.0 and is now DECLARED in 4.2.0, along with the new /version, /changes, /schema/{dataset} and /items/{id}/context routes. Only /stats, /images and /spec itself remain undeclared. Listed here as a gap for the provider; they are deliberately NOT added as path items, because this overlay does not author contract that the provider has not published. routes: - GET /api/v1/stats — per-dataset item counts plus latest scrape timestamp (probed 200) - GET /api/v1/images — all item image URLs (probed 200) - GET /api/v1/spec — the OpenAPI document itself (probed 200) - GET /api/v1/metadata?full=true — detailed metadata for all datasets - target: $.paths['/api/v1/weapons'].get description: Illustrative enrichment of one representative collection operation. Every collection route follows this shape. update: operationId: listWeapons tags: [weapons] description: >- List Gray Zone Warfare weapons. Supports equality filters on any string field, full-text search, sorting, and page-number pagination. Data is wiki-derived and refreshed by the weekly scraper. x-derived-by: API Evangelist overlay — the published operation carries only a summary. - target: $.paths['/api/v1/weapons/{id}'].get description: Illustrative enrichment of one representative single-record operation. update: operationId: getWeapon tags: [weapons] description: >- Retrieve one weapon by its exact slugified id (e.g. ak-12). Ids are matched exactly; use the collection route with ?search= to resolve a display name to an id first. A missing id returns 404 RECORD_NOT_FOUND. x-derived-by: API Evangelist overlay — the published operation carries only a summary.