Materials · v1.0.0
Keep preferred ordering details beside the material—not inside stock.
Four nullable fields describe one preferred source. Explicit schemas, tenant-bound search, and HTTPS-only URLs add a useful integration contract without inventing supplier, pricing, or purchasing systems.
Explicit representation
| Property | Maximum | Rule |
|---|---|---|
articleNumber | 120 | Nullable, trimmed, intentionally not unique |
supplierName | 200 | Nullable preferred company display name |
supplierWebsiteUrl | 2,048 | Nullable absolute https:// URL |
orderUrl | 2,048 | Nullable absolute https:// direct article/order URL |
Blank strings normalize to null. All four properties appear in list and detail representations even when null. The runtime selects and serializes an explicit allowlist, so an unrelated future database column cannot leak into the API. A legacy import that bypassed the write guard returns an invalid stored URL as null until an administrator corrects it; it never becomes an executable API link.
Search one collection
GET /v1/organizations/{organizationId}/materials?q=RC-42&active=true&limit=50q matches material name, article number, or supplier name case-insensitively. Whitespace is trimmed and special characters such as %, _, commas, and parentheses are literal text. Search stays inside the organization bound to the key and retains cursor pagination.
Create and update safely
POST requires materials:write and Idempotency-Key. PATCH also requires the latest ETag in If-Match. This synthetic body contains no customer data:
{
"name": "Roadside cleaner",
"unit": "litre",
"articleNumber": "RC-42",
"supplierName": "Synthetic Supply NV",
"supplierWebsiteUrl": "https://supplier.example",
"orderUrl": "https://supplier.example/articles/RC-42"
}Relative, HTTP, script, malformed-host/port, embedded-credential, ambiguous-backslash, and overlong links return 422. A stale update returns 412; missing If-Match returns 428. Ordering changes never rewrite location quantities or storage details.
Pre-adoption stability decision
The API remains /v1 and 1.0.0. Before release, issued-key inventory and gateway/access logs must still prove there is no external consumer. If one exists, stop for compatibility and version review.
The additive columns can ship before the employer/API build. Existing materials remain valid with null ordering fields; stock and the employee app’s explicit stock-only projection are unchanged. Roll application code back first and leave the nullable columns in place.