Responses

The envelope, pages, caching, ids, and versions.

The envelope

Every answer is JSON. What you asked for is under data. A list that comes in pages also carries next_cursor. An error carries error instead:

{ "error": { "code": "not_found", "message": "No such game." } }

Dates are ISO 8601, in UTC. Linked things are ids: a game names its teams, a player names their team. Fetch /teams and /modifiers once and look them up.

Pages

/players and /games come in pages. limit sets the size (up to 100; 50 by default). When next_cursor is not null, pass it back as cursor for the next page:

curl -H "x-api-key: hck_…" "https://hockay.com/api/v1/players?limit=100"
curl -H "x-api-key: hck_…" "https://hockay.com/api/v1/players?limit=100&cursor=MTAw"

Caching

Every answer carries an ETag and a Cache-Control: private, max-age=… that says how long it is good for: seconds for a live game, an hour for a final box score, a day for the arenas. Send the ETag back as If-None-Match and an unchanged answer comes back as an empty 304.

Ids

Versions

The v1 in the path is a promise. Within it, things are only added: new endpoints, new fields. A change that would break your code ships as /api/v2, next to v1, and v1 keeps answering.

The full description is an OpenAPI document. Point a client generator at it for Swift, Kotlin, or TypeScript.