Conventions

Six habits that hold across every endpoint. Each one is something to do, not something to know.

​

Compare values without case

Statuses and codes come back in the case the field uses, and that is not the same everywhere. Compare case-insensitively rather than matching exact strings, and you never have to remember which is which.

​

Read the shape of the response you got

A listing wraps its rows differently depending on the endpoint — some in a pagination object, some with the counters at the top level, some in a bare array. Read what came back rather than assuming the shape you saw on another endpoint. Pagination has all four.

​

Do not assume the request and the response mirror each other

What you send and what comes back are described separately for every endpoint, and they are not the same list. A field you send may not be returned, and a field you receive may not be sendable. The object page for each resource lists exactly what a read returns — start there rather than from the body you sent.

​

Parse amounts as decimals

Money arrives as a string: "1000.00", not 1000.00. Parse it with a decimal type. A float will round it eventually, and the first time you notice is a payment that is a cent short. The same goes for the fees on an account, which are decimal strings too.

​

Treat absent, null and empty as three things

A field can be missing from the response, present and null, or present and empty. They mean different things and your parser has to survive all three — a field that is null today may be absent tomorrow on a record where it does not apply.

​

Read the status code before the body

The status code is the one thing every response agrees on. Branch on it first, then on code where there is one, and treat everything else as text to display.