Flexible Identifiers

The Crossing Minds API supports various types to identify items and users:

Kind

Format

Description

integers

int<NBITS> or uint<NBITS>

<NBITS> is the number of bits in {8, 16, 32, 64}

UUID

uuid

accepts both uppercase and lowercase but always return lowercase, as described in RFC4122

hexadecimal

hex<NCHARS>

<NCHARS> is the number of bytes (up to 64), accepts both uppercase and lowercase but always return uppercase

url-safe

urlsafe<NCHARS>

<NCHARS> is the number of bytes (up to 64), uses the modified base64 alphabet of RFC4648

raw bytes

bytes<NBYTES>

<NBYTES> is the number of bytes (up to 64), useful to represent anything but needs to be base64-encoded when using JSON encoding

Validation and examples of various ID types:

ID Type

Validation Regex

Examples

uint64

\d+

406731410084687436

uuid

\h{8}-\h{4}-\h{4}-\h{4}-\h{8} where \h means [0-9a-fA-F]

5906d464-7ef1-4377-96e3-529f2ed6721d

hex10

[0-9a-fA-F]{1,10}

5906D464

urlsafe12

[0-9a-zA-Z._-]{1,12}

dQw4w9WgXcQ

bytes4

[0x00-0xff]{1,4}

0x5906d464

Database Settings

You need to configure the item ID type when creating a new database. This choice is permanent and cannot be modified later for this database.

See item_id_type and user_id_type in POST databases/.

ID Anonymization

If you need to fully anonymize your user IDs, we recommend to employ a secret one-way hash function and configure the database to use raw bytes. A common one-way hash function is sha1 with a secret salt, but other choices may be more suitable depending on your constraints.

If you need to anonymize your item IDs, you will need to employ a secret reversible cipher, so sha1 or other cryptographic hash functions cannot be used. This is because the API returns the IDs of recommended items, which you need to translate back to their hidden business ID. If no frequency analysis may be used to break the cipher, the simplest choice is the XOR cipher. Otherwise we recommend to use the AES cipher.