API Thinking Before Framework Thinking
If you define operations, data and failure cases before choosing a framework, you can swap the frontend almost at will later – the other way around, you get an API that mimics a framework.
API Thinking Before Framework Thinking
“Angular or React?” is considered the architecture question for new web projects this year. It isn’t one. It’s a tool question – and it is regularly asked before anyone has answered the question that actually is architecture: what are our operations and our data? This order is backwards, and right now it’s especially tempting. 2016 is the year of framework debates: Angular 2 has been final since September, Vue 2 came out at the end of September, React is at version 15, and the comparison articles fill conference programs, blogs and team meetings.
The dispute is entertaining, but it hides something simple: the framework only renders what an API provides. If you design the API first – resources or schema, names from the domain language, failure cases, permissions – you can choose the frontend almost freely afterwards and even switch it later. If you choose the framework first, you’ll very likely get an API that mimics exactly this framework’s data flow. And this API stays when the framework has long been replaced.
What an API defines – and what a framework defines#
A frontend framework decides how components are rendered, how state is managed in the client and how the team building the UI organizes itself. That’s not nothing, but it’s replaceable. There are plenty of migration stories from Backbone to Angular or from Angular 1 to React – this year, with the hard break between Angular 1 and Angular 2, more than ever. A framework switch is expensive, but it’s a local event: it affects the client and no one else.
An API defines something else, and for everyone involved at the same time:
- which operations exist and what they’re called,
- which data belongs together and which deliberately stays separate,
- which failure cases are expected in domain terms and what they look like,
- who may trigger which operation.
These four points survive every framework fashion. They form the contract between the business side, the backend and all clients – today’s web frontend, next year’s mobile app, the partner system of the day after tomorrow. A contract that changes forces changes on all contract partners. That’s exactly why it belongs at the beginning, not at the end.
The fourth point deserves a second look, because it’s the one most reliably run over by the framework-first approach. From the UI’s point of view, permissions look like a display matter: the button is hidden, the menu shortened, done. From the API’s point of view, they are an assurance – the statement that a particular caller simply cannot trigger an operation, no matter which client comes knocking. This assurance can only be given in the contract, not in the component. If you leave it out of the design, you add it later under time pressure, usually after the first call has shown up that no button ever triggered.
The wrong order in everyday project work#
I experienced what the backwards order feels like this spring in a project: order management for a retail customer, web UI first, mobile “sometime later.” The first three weeks went into framework evaluation – Angular 2 was still a release candidate, React with Redux the alternative, plus the usual side battles over TypeScript and JSX. The API was on no agenda. “We’ll do that once the frontend is in place,” people said, and they meant it honestly.
Once the frontend was in place, there was an API too. It had an endpoint /api/app-state that filled the complete Redux store on load. It had field names that came from the reducers, not from the domain language. Errors came as HTTP 500 with a text, because the client only showed a red message anyway. Permissions were checked in the frontend because that was more convenient there at the time. None of this was ill will – every single decision was reasonable from the frontend’s point of view. Taken together, the API was an imprint of the Redux data flow.
Half a year later, the mobile team arrived. It couldn’t do anything with /api/app-state, needed smaller slices, different error handling, real authorization on the server. The backend got a second API next to the first, and from then on both were maintained. The framework question, by the way, had been decided in favor of React back then – it would have made no difference to the result if it had been Angular. The expensive decision wasn’t the framework. It was the order.
Resources first: an example#
What does the other order look like? It starts with a conversation in which no framework comes up. With the business side at the table, you collect the terms that come up there every day anyway: order, customer, credit limit, cancellation. From these terms, a first resource design emerges – noted here as REST routes:
GET /customers/{id}
GET /customers/{id}/orders
POST /orders
GET /orders/{id}
POST /orders/{id}/cancellation
Two things about this design are more important than they look. First: POST /orders/{id}/cancellation instead of DELETE /orders/{id}. In retail, a cancellation is not a deletion but a domain process with its own rules – it can be rejected, it can trigger fees, it shows up in the history. The endpoint carries the name from the domain language, not the one from the HTTP textbook. Second: the failure case is part of the contract. When an order exceeds the credit limit, that’s not a server error but an expected domain response:
{
"order": null,
"failure": {
"code": "CREDIT_LIMIT_EXCEEDED",
"message": "Customer credit limit exceeded",
"creditLimit": 5000,
"openAmount": 5240
}
}
You can print this JSON and discuss it with the business side. “Is the error code right? Is a field missing? Is the field sales team even allowed to see this?” – such questions can be settled on a contract document long before a single line of frontend exists. They can’t be settled on a Redux reducer or an Angular service, because the business side never gets to see it.
The same thing thought of as a schema#
For a year and a half, there has been a second vocabulary for this contract work: GraphQL, published by Facebook in the summer of 2015 as a specification along with a reference implementation. With Relay, there was a client from the start; since the middle of this year, the Meteor team has been working with Apollo on a second, deliberately framework-neutral client family. What interests me about GraphQL for the design step is less the query mechanism than the schema shorthand notation. It forces you to write down exactly the things that API design is about:
type Order {
id: ID!
customer: Customer!
items: [OrderItem!]!
status: OrderStatus!
}
enum OrderStatus {
PLACED
APPROVED
REJECTED
CANCELLED
}
type OrderFailure {
code: String!
message: String!
}
type PlaceOrderResult {
order: Order
failure: OrderFailure
}
type Mutation {
placeOrder(input: PlaceOrderInput!): PlaceOrderResult
cancelOrder(id: ID!): CancelOrderResult
}
placeOrder and cancelOrder are named after the processes the business side talks about. PlaceOrderResult makes visible that an order can fail in domain terms without anything being technically broken – the same distinction as in the JSON example above, only this time anchored in the type system. Whether REST resources or a GraphQL schema form the contract in the end is secondary for the order. Both are notations for the same thinking: operations, data, failure cases, permissions – before the framework.
flowchart TD
subgraph FF["Framework first"]
F1[Framework choice] --> F2[Data flow of the<br/>framework] --> F3[API mimics the<br/>data flow] --> F4[Every new client<br/>needs a new API]
end
subgraph AF["API first"]
A1[Domain language:<br/>operations and data] --> A2[API contract:<br/>resources or schema] --> A3[Frontend freely chosen:<br/>Angular, React, Vue]
endHow to recognize a framework-shaped API#
The backwards order leaves traces that reliably turn up in code reviews. A few signals I now watch for:
- Endpoints that correspond exactly to one screen (
/api/dashboard,/api/app-state) - Field names from the client store instead of from the domain language
- Errors exclusively as HTTP 500 with free text, because the client only shows a message anyway
- Permission checks that exist only in the frontend
- Data formats that assume the internal structure of a particular client library
Each of these signals is harmless on its own and even efficient at the moment it comes about. Together they mean: this API has exactly one legitimate consumer, and that happens to be the framework that’s in the project right now. The second consumer – mobile app, partner integration, batch import – then pays the full price.
Backend for Frontend as an honest compromise#
Now, it would be dishonest to pretend that all clients have the same needs. A web frontend often wants broad, nested responses; a mobile app on a cellular connection wants small, pre-condensed slices. If you force the same generic format on both, you make both slow. For this tension, a pattern with its own name has become established since last year: Backend for Frontend, BFF for short. Sam Newman described it, SoundCloud demonstrated it in its own architecture – one thin layer per client type, dedicated to the respective frontend, with the one domain API behind it.
flowchart LR Web[Web client<br/>React or Angular] --> BW[BFF Web] Mob[Mobile client<br/>iOS and Android] --> BM[BFF Mobile] BW --> API[Domain API:<br/>Orders, Customers] BM --> API
The point that makes the pattern honest for me: the coupling to the client isn’t denied but named and fenced in. The BFF may be client-specific, may tailor responses, may even flatter a framework’s data flow – it’s the only place in the system where that’s allowed. The domain API behind it stays clean and framework-free. If you confuse the two levels, you end up back at the /api/app-state endpoint, only this time with a clear conscience.
It also matters who owns such a layer. At SoundCloud, each client team maintains its own BFF – the web team its own, the mobile team its own. That fits the logic of the pattern: whoever needs the tailoring is also responsible for it, and the domain API behind it doesn’t have to negotiate every client whim. If the backend team takes over all the BFFs instead, the compromise quickly turns into a bottleneck again, and the pressure grows to push the tailoring into the domain API after all.
Contract work is work with the business side#
Whether resources or schema: the design is only as good as the conversation it comes from. For REST APIs, Swagger has become established as the description format – officially, since the founding of the OpenAPI Initiative at the end of last year, the specification is called OpenAPI, but in everyday use everyone still says Swagger. The real value isn’t in the tooling but in the fact that there is a document that can sit next to the domain concepts in a review. A GraphQL schema does the same, in a more compact form.
I experimented in this direction myself this year: graphql-pouch, a small open-source project that generates a working API on top of PouchDB from a GraphQL schema notation, including CouchDB synchronization. The approach there is deliberately “frontend first” – get to a typed data model quickly without backend migrations. Interestingly, exactly this experiment confirms the thesis: even when the runtime accommodates the frontend, the first artifact is the schema notation. You write down types and operations before anything renders. The schema is the contract; everything else is output.
The contract work itself stays uncomfortable, and that’s a good thing. When the business side frowns at the name cancelOrder because no one in the company talks about “cancellation” but everyone talks about “reversal,” that’s exactly the discussion you want to have in December – not in June, when three clients have already hard-wired the name.
The bottom line#
The framework question can be fun, and this year’s answers – Angular 2, React 15, Vue 2 – are all defensible. But it’s the second question. The first is: which operations are there, what are they called in the domain language, which failure cases are expected, who may do what? If you answer this question in a contract document – as a resource design or as a schema – you make the choice of framework almost risk-free and a later switch affordable. If you skip it, you still choose the framework – only then it secretly co-designs the API, and that part of the decision can’t be corrected later with an npm install.
Further reading#
Revised and translated from German with the help of AI.