API Documentation
Authentication
Authenticating with the SIM API can be done using an OpenID Connect bearer token gained through the OpenID Connect API.
Snowflake
A snowflake is a unique ID scheme first used at Twitter. These IDs are unique across all organisations, as such they are stored as unsigned 64 bit integers. As all numbers are assumed to be type double in JSON, snowflakes are returned with a type of string.
SIM snowflake IDs use a similar high-low ID assignment to twitter which decentralises ID assignment with servers only needing to block to retrieve a high ID and can auto-increment to assign a low ID.
The client should use snowflakes to generate a nonce where they need to keep track of new IDs generated by the server. Nonce snowflakes should randomly generate all bits of the high-low. Nonces should be used where a replay of data submission to the server can result in duplicate data.
The SIM API snowflake will overflow in the year 2572, by comparisson the twitter snowflake will overflow in the year 2149 using an unsigned long or as soon as 2079 using a signed long. Using 16 ms accuracy is sufficient due to jiffies and timer coalessing which saves 4 bits on the timestamp and improves the randomness of nonces.
Snowflake ID Broken Down in Binary
|
Snowflake ID Format Structure
| Field | Bits | Number of bits | Description |
|---|---|---|---|
| Timestamp | 63 to 24 | 40 bits | Every 16 milliseconds since SIM Epoch, the first second of 2015 |
| Worker ID | 23 to 8 | 16 bits | There can be 65,536 concurrent workers |
| Increment | 7 to 0 | 8 bits | For every ID that is generated by a worker this number is incremented |
Nonce
A nonce is an anti-reply attack token. Many POST requests take a nonce to prevent synchronisation errors and double-posting. Nonce are in the form of a snowflake and must be able to be converted to a 64 bit unsigned integer. Where a nonce is expected and not a 64 bit unsigned integer, will return Bad Request with message Invalid nonce. Where a nonce has already been used, will return Bad Request with message Nonce already in use. You will be unable to use the same nonce once used.
Token
A token is a 6 character randomised alpha-numeric string. Tokens are not globally unique. Once a token has been used it can be recycled depending on the object type, and can be used by multiple organisations at the same time. There are 2,176,782,336 unique tokens. A 10-6 chance of collision will occur every 208 tokens and a 10-9 will occur every 6 tokens. That is it is very unlikely for duplicate tokens to be generated within a token space as the 50% chance is every 54,933 tokens.
Token generation must check for duplicate tokens.
Many transport booking systems already use 6 character passenger locator tokens which make them familiar to users. This user friendliness is weighed against their security. To further the token security, they should be combined with an identifying token such as a name, an e-mail address, or an object identifier.
Hash
A hash is a SHA-256 cryptographic hash of all the data that is part of an immutable object. Immutable objects are otherwise known as copy-on-write and preserve the full history of an object. The SHA-256 hash of the title of this document is 1cc77e60fcee8c4392cc52a2fdd1d9129beed4e6af97aca1b78ea61362c85247. This is represented as a hexadecimal string and is not case sensitive. As this hash is 256 bits long, it should be stored and compared in hexadecimal form as a string with a length of 64.