For systems that need to be built against, not just built
API Development
An API is a promise to every system that builds against it, and most API problems are broken promises: undocumented behaviour, silent breaking changes, contracts nobody versioned. This practice treats the contract as the deliverable, whether you are exposing something internal, integrating a partner, or modernising an API too fragile to touch.
How an API contract gets designed here
Versioning, authentication and the documentation consumers actually need.
90 secSample frame · video pending01Before writing an endpoint
REST or GraphQL is a real decision, not a preference.
The choice gets made too casually, usually based on what an engineer used last. Four questions settle it against your actual consumers.
Do consumers need flexible, varied queries?
GraphQL earns its complexity when consumers genuinely need different data shapes. If every consumer wants roughly the same thing, REST is simpler to reason about.
How many consumer teams will you support?
A small number of known consumers tolerates REST's rigidity fine. Many unknown future consumers benefit from GraphQL's self-describing flexibility.
What is your caching strategy?
REST's resource model caches simply at the HTTP layer. GraphQL requires more deliberate caching design, which is real engineering effort either way.
What does your team already know well?
The theoretically better choice matters less than the one your team can operate confidently under production pressure at 2am.
| REST | GraphQL | |
|---|---|---|
| Query flexibility | Fixed per endpoint | Consumer-defined |
| Caching | Simple, HTTP-native | Requires deliberate design |
| Learning curve for consumers | Familiar, lower | Steeper, more powerful |
| Best fit | Known, stable consumer set | Many varied consumers |
02Agreed before the contract is written
The ledger that keeps the API honest
API engagements fail when scope of exposure is assumed rather than agreed. This ledger fixes what you bring, what we design, what returns, and what stays under your control.
- Your side
You bring
- The internal system and its current interfaces
- Who the API needs to serve, internally or externally
- Any existing consumers already depending on it informally
- Our side
We build
- A versioned, documented API contract
- Authentication and rate limiting appropriate to the consumers
- Backward-compatible evolution from whatever exists today
- Your side
You receive
- A production API with published documentation
- A versioning strategy that will not break consumers
- Monitoring for the endpoints that matter most
Never leaves you
- The business logic and data behind the API
- Authority over what gets exposed and to whom
- The roadmap for what the API supports next
Where the line sitsWe design the contract; you keep the decision on what the system should actually expose. A well-designed API can hide more than it reveals, deliberately.
03From contract to production traffic
Four stages, each closing on evidence
APIs that break consumers usually skipped a stage here. This system closes each one with something a consuming team could actually build against.
Design the contract first
Endpoints, schemas and versioning are specified and reviewed with consuming teams before implementation starts, catching mismatches while they are cheap to fix.
A contract consumers can reviewSecure the boundary
Authentication, authorization and rate limiting are matched to who is actually calling the API, from internal services to external partners.
Authentication that fits the trust levelBuild and document together
Documentation is generated from the same source as the implementation, so it cannot silently drift from what the API actually does.
Documentation that matches realityShip with observability live
Error rates, latency and usage per consumer are visible from day one, so a problem is caught by a dashboard, not a support ticket.
Monitoring before the first real consumer
04What actually moves the number
Four drivers, priced from the contract
API work is priced against the assessment, because these four factors change scope by multiples.
Number and complexity of consumers
A single internal consumer is simpler than a public API serving unknown third parties with varied needs and expectations.
Authentication and authorization depth
Simple API keys cost less than OAuth flows with fine-grained scopes, which many partner integrations genuinely require.
Legacy behaviour to preserve
Modernising an existing API costs more when years of undocumented consumer dependencies must be discovered and respected.
Documentation and developer experience
A public-facing API justifies more investment in interactive documentation and SDKs than an internal service consumed by one team.
05Evidence and proof
Contracts that held as consumers multiplied.
API proof is zero breaking changes and documentation that matches reality. Every record here waits for written client approval before production.
Explore case studiesAn internal system opened to three partner integrations without an outage.
Orra Systems needed to expose core workflow data to partners for the first time. A versioned API with scoped access shipped three integrations without a single breaking change.
- Partner integrations shipped
- 3
- Breaking changes to consumers
- Zero
A five-year-old unversioned API modernised with zero consumer downtime.
Nexa Foundry's core API had no version history and undocumented consumer dependencies. A versioning strategy let old and new consumers coexist through the migration.
- Consumer downtime during migration
- None
- Undocumented dependencies found
- Mapped and preserved
The documentation matched the actual API on day one, which our own team had never managed in three years of trying.
Sample · pending client approval
06Read this first
When a new API is the wrong answer
Building a formal API contract for one internal caller that will never change is over-engineering. The exits are marked plainly. When an API is justified, it runs on Node, Python and Java, with OpenAPI or GraphQL schemas and standard cloud infrastructure.
There is exactly one internal caller
A direct function call or internal library often serves this better than API overhead nobody else will ever use.
- Software architecture
The data model is still changing weekly
Formalising a contract on an unstable data model means renegotiating it constantly. Stabilise the model first.
- Team extension
You need API engineers, not a delivery layer
If your team already owns the API strategy and needs capacity, team extension fits better than a commissioned build.
| Shape | Best when | You direct | We carry |
|---|---|---|---|
| Scoped build | Consumers and scope are known | Access decisions and priorities | Contract design and delivery |
| Delivery pod | Consumer needs will evolve | Product decisions each cycle | Engineering and documentation |
| Team extension | Your leads own the API strategy | Architecture and standards | Named engineers and continuity |
07Straight answers
Asked before an integration budget is approved.
01Do you build REST or GraphQL APIs?
Both, chosen against your actual consumer needs rather than a default. Most engagements start by mapping consumer query patterns, which usually settles the question clearly.
02How do you handle API versioning?
Through an explicit strategy agreed before the first version ships, whether that is URL versioning, header-based versioning or schema evolution. The strategy is chosen to let old and new consumers coexist during any transition.
03Can you integrate with our existing authentication system?
Yes, API authentication typically integrates with whatever identity provider or authentication system you already run, rather than introducing a separate one to manage.
04Do you write the API documentation?
Yes, generated from the same source as the implementation so it cannot silently drift out of date. Interactive documentation that consumers can test against is standard for anything public-facing.
05What does API development cost?
Priced against the number of consumers, authentication complexity and documentation depth required, from the scoping assessment. A single internal API costs less than a public, partner-facing one.
06Can you modernise our existing API without breaking current consumers?
Yes, and that constraint shapes the entire approach. Versioning and a genuine deprecation window carry existing consumers through the change rather than forcing a hard cutover.
07Do you build the API and the system behind it, or just the interface?
Both, when the engagement calls for it. API development, product engineering and data work share this practice's delivery discipline, so a new API rarely means introducing a separate vendor for the logic behind it.