The same card has a different ID in every language

A bad language code gets its own error

This session sent GET https://api.tcgdex.net/v2/xx/cards/swsh3-136. The API returned HTTP 404 with a JSON body. The type field was https://tcgdex.dev/errors/language-invalid.

The details field lists the 18 valid codes: en, fr, es, es-mx, it, pt, pt-br, pt-pt, de, nl, pl, ru, ja, ko, zh-tw, id, th and zh-cn. A client can read this list to build a language menu.

A bad path gets a different type. GET https://api.tcgdex.net/v2/nosuchpath returned HTTP 404 with the type https://tcgdex.dev/errors/not-found. The endpoint field in that body was /v2/nosuchpath. In the language error, the endpoint field was /xx/cards/swsh3-136, with no /v2 prefix.

A card ID that works in English fails in Japanese

GET https://api.tcgdex.net/v2/en/cards/swsh3-136 returned HTTP 200. The card is Furret from the set Darkness Ablaze. GET https://api.tcgdex.net/v2/ja/cards/swsh3-136 returned HTTP 404 with the type https://tcgdex.dev/errors/not-found.

The Japanese catalogue uses its own set codes. A search for the Japanese name, GET https://api.tcgdex.net/v2/ja/cards?name=オオタチ&pagination:itemsPerPage=3, returned the IDs SV9-077, SV9-110 and MC-571. Do not store one card ID and swap only the language in the URL. Look the card up again by name or by set in each language.

The name filter matches part of a name

GET https://api.tcgdex.net/v2/en/cards?name=pikachu returned 243 cards. The first two on this session's request were fut2020-1 ("Pikachu on the Ball") and basep-1 ("Pikachu"). The filter matches a substring, so the full list includes cards with extra words in the name.

Add pagination:itemsPerPage=2 to limit the list. With pagination:page=2, the API returned tk-hs-r-2 and 2024sv-2. The order is not alphabetical.

The list rows hold only id, localId, name and an image link. A request for one card by ID returns the set, rarity, illustrator and variants.

GraphQL works without a key, and CORS is a wildcard

A POST to https://api.tcgdex.net/v2/graphql with the query { card(id:"swsh3-136"){ name } } returned HTTP 200 and {"data":{"card":{"name":"Furret"}}}. No key or header was needed beyond the content type.

A GET with the header Origin: https://greatapis.com to /v2/en/sets returned access-control-allow-origin: *. An OPTIONS preflight to /v2/graphql returned HTTP 200 and allowed GET, POST and OPTIONS. Browser code on any site can call this API directly.

The REST responses carry cache-control: no-cache, no-store, must-revalidate. Cache the responses in your own app if you load many cards.