To keep the API simple to understand and integrate, we re-use the same design principles and common patterns throughout.
The URL structure is always:http://localhost:4000/api/[class].[method]
For example http://localhost:4000/api/session.create
All methods that operate on the same class (or object) are bundled together.
Most classes have the same common methods, such as:
• create for creating a new object
• get for retrieving an object by id
• list for retrieving a filtered list of objects
• update for updating an existing object by id
• delete for deleting an object by id
A method is always returning an object or a list of objects of the class that is being requested.
Responses are always flat and do not contain nested objects.
Property names, such as id, always refer to the same class.
If referring to another class, the property name is prefixed with that class.
Some properties are guaranteed to always have the same type and format:
• Ids are always 64 bit integers
• Enums are always strings
• Timestamps are always strings, in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ
• Dates have the format YYYY-MM-DD
• Times are always expressed in UTC
• Float, double or decimal values are always strings (e.g. “10.50”)
• Countries are denominated by two-letter ISO 3166 codes (e.g. “US”)
• Currencies are denominated by three-letter ISO 4217 codes (e.g. “USD”)