Identifiers

Every identifier in this API looks like rc_1WNM9X2: a two letter prefix, an underscore, then a short string of letters and digits. They are safe to store, safe to log and safe to put in a URL.

The prefixes

Why the prefix earns its place

It is not decoration. Passing a horse identifier where a race is expected returns 422 invalid_id rather than 404, and rather than the wrong race. Two bare integers would have silently resolved to different things, and that class of bug is expensive to find because nothing errors.

GET /v1/races/hs_1G0HAZH

{
  "error": {
    "code": "invalid_id",
    "message": "That is a horse identifier. This endpoint expects a race."
  }
}

They are opaque, and that is deliberate

The identifier is not a database row number. It is a reversible transform of one, so it carries no ordering, no volume information and nothing you can iterate through. Two races created a second apart have identifiers that look nothing alike.

That protects both sides. It stops anyone enumerating the archive by counting upward, and it stops the identifier accidentally revealing how much data we hold or when a record was created.

They are stable

An identifier for a given thing never changes. It is derived from the source's own record, not from a sequence, so it survives a reload, a rebuild of the serving database and a restore from backup.

Store them. Use them as foreign keys. Cache against them. The only thing that would change them is a deliberate versioned migration, which would be a new API version and announced on the changelog.

What not to do

• Do not construct one. They come from responses. There is no valid way to build one and a guess will not resolve.
• Do not parse one. The characters after the prefix carry no meaning you can use.
• Do not compare across types. A race and a horse can never share an identifier, so equality between different prefixes is always false and never interesting.
• Do not lowercase them. The alphabet is case-sensitive.

The one that is different

Owner identifiers are derived from the owner's name, because the source publishes no owner identifier at all. They are stable and they round-trip, and they are exactly as reliable as the name.

Which means a syndicate written two ways is two owners, and "Mrs J Smith" and "Mrs Jane Smith" are two owners. We do not merge those, because there is no identifier to check a merge against and guessing produces confident, wrong answers. If your analysis needs them combined, only you can decide that they are the same.