Field Naming & Data Structure Guidelines
This document describes our internal API field and structure guidelines, which we share publicly so you can better understand how and why we design our API the way we do.Field Naming & Data Structure Guidelines
1. Field Naming Rules
UIDs
All fields that reference a technical unique identifier must end with Uid.
Example: productUid, orderUid
Quantities
All fields that reference a stock or quantity must start with quantity.
Example: quantityOrdered, quantityInStock, quantityReserved
Entity References
Fields that refer to another entity must always use the same field name as in the original entity.
Example: If an order line references a product, the field must be called productUid.
2. Field Types
Uid — Required unique identifier (string)
OptionalUid — Optional unique identifier (string)
Use Uid when the reference is required.
Use OptionalUid when the reference is optional or can be unset.
3. Clearing Fields
Text fields — Clear by sending an empty string "".
Uid fields (OptionalUid) — Clear by sending an empty string "".
Date fields — Clear by sending null.
4. Lists & Search Responses
All list and search endpoints must return:
items — The array of results.
paging — Pagination information.
5. Pagination Rules
The paging object must include:
Field
Description
totalCount
Total number of elements in the result set.
pageNumber
Current page number (defaults to 1 if not provided).
pageSize
Number of items requested per page.
Example:
A search with 27 results and pageSize = 24:
To check if there are more pages:
If items.length < pageSize, this is the last page.
This format keeps your internal rules crystal-clear for your own developers, but also makes it easy for external devs to understand how to structure their requests and interpret responses.
Last updated