https://api.quidkey.com/v1. An endpoint that departs from one says so in its reference, and why.
- One shape per resource. A resource is represented the same way by every endpoint that returns it.
- One document shape. Every successful JSON response has the same structure, whether it holds one resource or a hundred.
- Invalid input is refused. An unknown field, an ambiguous value or an amount we can’t represent answers an error. It’s never guessed at, rounded or dropped.
- Changes. We add to the API without notice, and change or remove what’s published only as Versioning describes.
Representations and Views
Each resource has a full representation, and some also have a summary, with the fields needed to display or choose between resources. The view a response holds is in its_view field. A single read takes ?view= to choose any view the resource documents, and a list returns its documented view.
- A summary is a strict subset of the full representation, with the same names, types and meanings.
- A representation looks the same wherever it appears: from a list, a read, a create, an update or an action.
- A representation doesn’t vary by caller. If you can read a resource, you see what anyone else who can read it sees.
- Every field is always present. An empty value is
null, and an empty collection is[]. The one exception is a one-time value, such as a secret, which appears only in the response that issues it. See Idempotency. - Sensitive values, such as bank account numbers, aren’t returned in full.
Fields starting with an underscore belong to the protocol. All other fields belong to the resource.
Links
A relationship is always a link object, never a bare ID, with the same shape for every resource:is_default on a country’s payment scheme.
A link gives no access of its own. A response can link to a resource you can’t read, and fetching it answers 403 or 404.
URIs
A resource has exactly one canonical URI, flat wherever its ID is unique, such as/transactions/tx_1. A sub-collection such as /merchants/m_1/transactions returns resources carrying those canonical URIs.
URIs are relative to the version root and don’t contain /v1, so resolve one against your base URL, https://api.quidkey.com/v1. A URI never changes for the life of the resource.
Response Documents
A successful response has three parts:resultholds what you asked for: one resource, or an array for a list.entitiesholds linked resources, keyed by URI: those the endpoint includes by default, and those you ask for withinclude.not_includedlists the links that should have been included but couldn’t be.
?view=summary to keep it short:
?include=merchant leaves result unchanged and fills entities, so a client finds a linked resource the same way every time:
result, with pagination beside it. See Collections.
Including Linked Resources
includetakes a comma-separated list of link fields, one level deep:?include=merchant,customer_details. An unknown field answers 400. Each endpoint’s reference lists what it can include.- Sending
includereplaces the endpoint’s default inclusions, so?include=with no value includes nothing. - Including an array of links hydrates each one. A collection link can’t be included: follow it instead.
- Each URI appears once in
entities, however many links point to it. An included resource is inentitieseven when it’s also inresult. - A representation is identical in
result, inentitiesand when you fetch its_uriwith the same view. - A direct read and the response to a write are authoritative. A resource in a list can be slightly older than a direct read.
Links Not Included
A resource that should be included but can’t be read is left out ofentities and listed in not_included, with its link and a reason. result stays the same.
A link you didn’t include has no entity. Fetch its URI if you need it.
Formats
Money
Money is always an object, with an integervalue in the currency’s ISO 4217 minor units and its currency code:
- GBP 45.00 is
4500. Each amount carries its own currency, so two amounts in one resource can differ. - The same form is used in requests and responses. Two places write money otherwise: a file writes an amount as a decimal in major units, and an event’s earlier fields write it in their own forms, such as a string of minor units with its currency beside it.
- A decimal value is refused, not rounded, and so is a currency we can’t process.
Rates
A rate is a decimal string holding a fraction:"0.0500" means 5%. Parse it as a decimal, and don’t assume a number of places: it has at most 8, and trailing zeros aren’t significant. A field holding a percentage is named *_percent, such as ownership_percent.
Points
Reward points, as inextra_rewards and total_rewards, are a decimal string, not money: "12.50". A response gives exactly 2 decimal places, and a request takes at most 2.
Dates and Times
A timestamp means what its name says:
sent_at is when a payout was sent, never when its record last changed.
Other Values
Input is parsed and output is canonical, so a time sent with
+00:00 comes back with Z. A value we can’t represent is refused, never dropped.
Names
- Fields and parameters are
snake_case, and path segments arekebab-case. - An action is named in
lowerCamelCase, after a colon::issueCheckout. - Collections are plural and singletons are singular, as in
/merchants/m_1/onboarding. - Booleans read as predicates:
is_test,has_more,can_refund. - Enum values are lowercase
snake_case. We spellcancelledwith two Ls. - A resource that reports why something failed carries
failure, an object with at leastcodeandmessage, ornull.