API Development in New Zealand

Who is on the other end?

This one question sets the price, and most briefs do not answer it.

Only your own software. The API is a private arrangement between two things you control. Change it whenever you like, deploy both ends together, and skip most of what follows. This is the cheap version and there is nothing wrong with it.

A handful of named partners. Now other people's release schedules matter. You need versioning, a sandbox, and documentation, because a partner's developer will read it at 9pm in another timezone and must not need to ring you.

Anyone who signs up. The API is now a product. Self-service keys, usage limits, metering, support, and the permanent inability to change anything quietly.

Say which one you are building in your brief. Quotes that differ by a factor of four are usually quotes for three different answers to this question.

The endpoints are the small part

Any competent developer can expose your data over HTTP in a week. What takes the other eleven:

• Authentication — issuing keys, letting a customer rotate one that leaked, supporting two live at once during a changeover.
• Errors a stranger can act on. "500 Internal Server Error" costs you a support email every time. "Field `invoice_date` must be ISO 8601" costs you nothing.
• Rate limiting — so one partner's runaway script does not take the API down for everybody else.
• Pagination — decided on day one, because changing how results are paged later is a breaking change.
• Idempotency — so a retried request does not create a second order. This is the single most common omission and it produces duplicates in your database that nobody can explain.
• Documentation that is true, generated from the code rather than written once and left to rot.

Ask each developer which of these are in their quote. The differences will be larger than the prices.

Versioning: decide before you need it

You will eventually need to change something in a way that breaks existing consumers. The plan for that moment should exist before the API ships, because retrofitting one is much harder.

What a workable answer sounds like:

• The version is in the URL — /v1/ — or in a header, decided and written down.
• Additions are not breaking changes; removals and renames are.
• When v2 arrives, v1 keeps running for a stated period. Six or twelve months is normal.
• There is a way to tell consumers, which means you know who they are and how to reach them.

That last point catches people out. If your API has no signup and no keys, you have no list of who is using it, and no way to warn them.

REST unless you can say why not

REST is understood by every developer who might integrate with you, cached by ordinary infrastructure, and debuggable with tools your partners already have. It is the default for good reasons.

GraphQL is genuinely better when consumers need very different shapes of the same data — a rich application with many screens, each wanting a different slice. It costs you more in caching, rate limiting and controlling expensive queries, and it narrows the pool of people who can maintain it.

If a developer proposes GraphQL, ask what problem it solves in your case. A good answer is specific. A bad one is that it is modern.

Write the documentation first

The most useful thing you can do before any code exists is describe the API as though it already worked: the endpoints, the fields, an example request and an example response.

Do that and three things happen. Your developers build against an agreed shape rather than inventing one. Your partners can start work in parallel. And the arguments about what a field means happen on a document instead of after launch.

Written as an OpenAPI description, it also generates your reference docs, your sandbox and your client test tools for free. Ask whether the quote includes one.

Somebody has to answer the emails

A partner or public API creates a support obligation that never appears in a build quote. Someone at your end will be asked why a request failed, whether a field is optional, and what the rate limit is.

Decide before launch whether that is a shared inbox, a named person, or a rota, and budget the time. Good documentation and good error messages reduce it enormously, which is the practical argument for paying for both.

Comparing five quotes

Read for:

• Who asked who the consumers are before quoting?
• Whose quote names versioning, rate limiting and idempotency without being prompted?
• Who includes an OpenAPI description and generated documentation?
• Who described how a customer rotates a leaked key?
• Who talked about the support load after launch?

Describe who will call the API, what they need from it, and whether you will be able to change it later. Developers who have shipped a partner API will start asking about deprecation before they start asking about endpoints.