Flexible Identifiers¶

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

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.

Note that the speed of some internal processes is proportional to the size of the IDs. Therefore choose this setting carefully! Do not use the maximum length like urlsafe64 if you are planning to use only 8 characters, since doing so these processes would be 8 times slower than necessary.

See item_id_type, user_id_type and session_id_type in POST databases/.

ID Anonymization¶

If you need to fully anonymize your user IDs or session 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.