APIs all the way down
Weeknote, w/c 8 December 2025
We’re getting toward the end of our alpha looking into how we might approach redesigning the NHS App in native code. We’ve tested lots of ideas, discarded plenty, and are now trying to tidy things up ahead of planning for the next phase of work. It is an odd piece of work because we’re trying to set out a vision for how to improve the design of the App but we still have to deal with most of the constraints of the live app.
At this point, I feel like a broken record mentioning how messy and weird the health data landscape is. This isn’t a secret to anyone – it is why the Single Patient Record has been proposed, but that is still just an idea and we need to deal with the present reality. We’re doing lots of technical spikes and looking for the edges of the possible. Most of the data sources we need to incorporate sit outside of our direct control. Their structure, format, and performance levels all have a massive impact on what we can deliver, so naturally we’re spending a lot of time trying to understand the various interfaces (APIs) we use to access said data.
This past week I also had occasion to discuss the way we interface with different teams. This has always been a common topic around here because of how central the NHS App is to so many of the organisation’s plans, but it is becoming more problematic. We don’t have a single, clear, and concise description of what is permissible and how things work. That gap is starting to show up as conflict and confusion. Right now, most of my energy is directed at the design and research work in our native alpha, but once we’re through with this phase I suspect I’m going to need to turn my attention toward this meta-design project of how we deal with everyone else. I’ve known this was coming because it will be critical to changing our fundamental approach but I’ve been putting it off for a while.
We obviously need rules for who can do what. The questions are: what specific rules and who gets to decide them? We’ve tried to develop this kind of thing before but it never really sticks. That might be because no one else knows these rules exist, they don’t care about them, or because the org keeps rearranging itself and the rules we once wrote no longer work. I dunno.
I’ve been googling stuff like “what makes for good API design?” as a way of trying to approach the task from sort of new angles. As a technical dilettante, I realise this opens me up to all manner of possible blunders of understanding. It is fine, it is mostly just for fun and to get me out of a rut, a bit like using Oblique Strategies. (As a design methods nerd, I am often a bit flustered by the industries’ incapacity for imagining new frames of reference, but that is a subject for a different day.) To that end, topics like error handling, layer independence, versioning, caching, performance, and nesting all suggest elements of a collective working relationship that I can explore and play with. Some examples:
- Error handling: How do we respond when something goes wrong in a working relationship? What are the escalation paths and who gets to decide?
- Versioning: Do we maintain more than one version of how things should work, allowing teams to continue working to the guidance that existed when they first engaged with us?
- Performance: What is a reasonable response time for queries about whether a thing can or can’t be in the NHS App?
- Layer independence: What is our expectation of other teams when we ask for changes to their service so that they better fit within the way the App does things?
- Nesting: How large of an area of the App can non-App teams own? What is the correct level of scale for any given thing we plug into the App? For instance, should we be working to the idea of plugging in discrete services, or could a non-App team own a whole section of the App?
Aside from wanting to tame the chaos a little, the interesting element of this for me is how messing with these parameters might open or close possibilities for what the App’s patient-facing interface could be. As an example, if we were to shift the App team’s focus to native design systems and act more like a platform team, maybe we can let more people use the tools we make and build things in our codebase directly. If we did that we would open the question of who gets final say on the structure of the App at large and how conflict is resolved. To make situations like that work well we’d need a working agreement for inter-team communication and delivery. We’d need an API.
This applies as much to teams who sit outside of our programme as to those inside the App bubble. This native alpha is exploring how we might redesign the App using native platform conventions and design systems. To explore that, we need to work on things that exist in the App right now, so we’re redesigning things that other teams own. That gets awkward. How far do we actually go with redesigning a prescription request journey or the messages section of the App? At a certain point we might stumble into a situation like “Hi team responsible for X. We’ve redone your thing for you. You’re welcome.” Very awkward, but potentially necessary. Moving out of this phase of work, we’re going to need some ground rules about how we engage with other App teams and who owns what.
In designing the NHS App, our issues aren’t just the structures of the data we have access to or the performance of the end-point systems, we must also contend with how people are arranged and relate to one another’s area of control. If it takes 10 seconds for the NHS App to get a response from a someone else’s server, there is no amount of interface design wizardry that is going to save the product. Likewise, if we don’t have guarantees about the half-life of new integrated services, we might end up the de facto owner of a codebase we didn’t make and don’t understand. In this world, org design is as important as technical architecture.
There are so many options for how this might play out in the future. Lensing in and out, we’re trying to consider how changes to the patient-facing interface layer will necessitate changes to the team interface layer, all of which is constrained by the data interface layer. It is just (something like) APIs all the way down.
I’ve read a few very good things recently:
- Governance and labelling are the hard part, by Abby Covert. The note on labelling is very true, but the bit about governance is where I personally experience pain on a regular basis: “Everyone wants to talk about the fun stuff – the categories, the hierarchies, the clever labels. But the yucky work of deciding who owns what and how changes happen? That’s what makes or breaks your system.”
- The design is the code?, by Ruth Malen. This is about software engineering and architecture, but it is also excellent advice about how to write a design history post.
- Everything I got wrong about product (so you don’t have to), by Paul Brown. I know it says “product” in the article title, but this covers all things digital. Much of this will seem like common knowledge, but it is nice to see it repeated again. Point 8 rings particularly true for me. IMHO the only reason to pay attention to what users say they want is if it can open up an line of enquiry into how they got to that idea. The ideas themselves are almost always worthless.
- Must-haves when starting or joining a product team, by Steve Messer. We have onboarding docs for people joining the NHS App programme and this is going straight to the top of the list of things for new starters to read.