Conventions
Design principles and naming patterns that make the Seamless OS API consistent and predictable.
The Seamless OS API keeps to the same design principles on every endpoint. Read these conventions once, and the rest of the API behaves the way you expect.
Identifier naming
Specific identifier names. An identifier field carries the name of its entity:
subscriptionId, customerId, productOfferingId. We do not use a generic id field, so a
payload never leaves the entity type in doubt.
One name in every object. The same entity always has the same identifier field name. You can join and filter on that one name across every endpoint and every response.
Common identifier patterns
| Entity | Identifier Field |
|---|---|
| Customer | customerId |
| Subscription | subscriptionId |
| Order | orderId |
| Product Offering | productOfferingId |
| Payment Link | paymentLinkId |
| Payment Session | paymentSessionId |
| Invoice | invoiceId |
| License | licenseId |
Backward compatibility
The API changes continuously. This contract tells you which changes to expect at any time, and which changes we treat as breaking.
Changes to expect at any time
Your integration has to tolerate all of these:
- New fields in a response. Response objects are open. We add fields to them as the platform grows, and a field you never saw before can appear in any response.
- New endpoints, beside the existing ones.
- New optional fields in a request body. These never change what is already required.
- New webhook event types, and new fields in the payload of an existing one.
Your code has to do one thing for this: ignore fields that you do not recognize. If you generate a client from our specification, examine how that client treats an unknown property. Some generators reject an unfamiliar field outright. A routine addition on our side then becomes a failed request on yours. Most generators have a flag for this.
Changes we treat as breaking
A breaking change never reaches your integration unannounced. We pin your API key to a revision, and we publish a breaking change as a new revision. Your key keeps its revision until you move the pin. Versioning gives the full contract.
These are the changes we treat as breaking:
- We remove or rename a field, an endpoint, or a webhook event type.
- We make an optional request field required, or we narrow what a field accepts.
- We change the type or the meaning of an existing field.
- We add a value to an existing enum. A generated client turns an enum into a closed set of constants, so a new value fails to decode. This makes the addition breaking in practice, whatever the specification permits.
Request bodies are strict
A request body is the mirror image of a response. We reject a body that carries a field the
endpoint does not define, and we do not ignore it. A misspelled property name gets a 400
that names the offending field, not a value that disappears without a word.