APX is to API as UX is to UI

An API is the set of “switches and levers” that a software service exposes so that other programs and services can interact with it. You can request data from the service through its API, and with the proper permissions you use the API to send data to the service. Various software programs have had APIs of one sort or another for decades. But with the advent of Software as a Service (SaaS), and the massive proliferation of SaaS providers and increasing granularization of their offerings, APIs have taken center stage in the value chain. It feels like every piece of software, every device, every thing either has an API or will soon have one. There’s a growing realization of an entire API economy, with all the trimmings: providers of core services, aggregators, utility service providers, monetization plays, registries, and of course conferences and meetups, as well as trends and initiatives such as the consumerization of enterprise APIs. It’s certainly a thrill ride now in the API space, and so many new developments to write about. For today I wanted to concentrate on the germ at the center: the API specification itself. An API spec is a contract: it describes precisely those switches and levers and the behaviors they produce. Since the first consumer of a spec is likely a human, specifically a developer (yes, we are human!), a spec is at the very least a piece of documentation. Many specs never go beyond that: they are documented, for better or worse, and are left to the interpretation of their readers. So there’s a lot of value of codifying the API spec more precisely – precisely being defined as something that a machine can interpret unambiguously. For example, SOAP web services, the accepted standard is the Web Services Description Language (WSDL), a very rich XML dialect. The problem is that WSDL and similar standards have sacrificed human readability for machine readability. And no one in their right mind wants to write this huge pile of XML. So what’s a lazy (in a good way) developer to do? Of course, auto-generate the WSDL. The developer implements an API, annotates it (@WebService, etc), and magically the WSDL XML description of that API is emitted. The contract is ready to be published and consumed. What’s wrong with that? Let’s look at an analogy. In some ways, an API spec is a bit like a marriage contract: an agreement between two parties promising to exhibit certain behaviors reliably, for a long time, so both parties can build upon them. But can you imagine starting out adulthood by picking out a wedding band, buying a house, furnishing it, putting in a crib and a changing table, installing drapes and artwork, describing all this in a contract, and then trying to attract a potential spouse, hoping against all odds that he or she will find everything just right? Surely you have to start a bit more iteratively, dating for a while, maybe living together, trying out various places and arrangements, and when things feel right then tying the knot. You start with the desired experience, iterate until it’s just right, and then enter into a contract and implement. And if things aren’t quite right? Well, you can always version and make some changes… But before risking overstretching the analogy, let’s get back to safer ground. The point is: implementing your APIs and then hoping they work for their consumers is really putting the cart before the horse. You need take a design-first approach to API construction.Before you touch a line of code, consider what value your service needs to offer its consumers, and exactly how those consumers will need to consume it. Allow time to get this right. Iterate on the design, mock it for the consumers to play with, and in parallel ensure it’ll be deliverable by your implementers. You don’t need to implement anything at this stage, rather, drive towards mutual agreement on the form of the deliverable, the degrees of freedom, the payloads, the acceptable response times. Nail down the needs iteratively, and when they seem to work, fix them in place with a version tag on the contract. Now your consumers can start to prototype and develop the clients on their own, in parallel with the API implementers, because they know exactly what the implementation will end up delivering – mocks should be sufficient. And your API implementers know exactly what they need to deliver, which is bound to improve the chances they’ll really do so. To do this really well, let’s consider another, closer analogy, in human-computer interfaces. When an application or service needs to interact with people, it exposes a UI, hopefully a useful and attractive one. But for years now, the real killer apps have been designed with the entire User eXperience, or UX, in mind. UI design shops have been offering end-to-end UX design services and a holistic approach to the human-computer interaction. To fully optimize how the user and the app will derive value from each other, you have to compose the various UIs into a whole UX. Similarly, when your user is another computer, you must take into account the whole APX – the end to end Application Programming eXperience. For example, a mobile app that supports remote field engineers will present a very different UX, and will require a very different APX of its service providers, than will an app running in the corporate office connected over a 10GB ethernet line, even though they both rely on the same logical set of services. Data sources will need to be pre-combined server side to minimize round trips, data will need to be stripped down to its bare essentials to minimize bandwidth, aggressive caching and conflict resolution APIs will need to compensate for intermittent connectivity: all of those are APX concerns. One size rarely fits all in the world of APIs, so multiple sets of APIs are needed to support different APXs. Today’s top API architects are engaging their stakeholders early on in agile API design iterations, creating smart APIs by thinking through the entire APX. But how do you do effective APX? How can you design a suite of APIs tailored to a certain experience without having to actually implement them, and test and iterate until they feel right, involving your consumers – say, mobile app builders – at every step? How would you do that in the enterprise world as well as on the open web? And what if your API isn’t XML/SOAP-based at all: after all, most modern API providers and consumers are looking to RESTful paradigms? There’s a bit of a vacuum in APX land; and nature, as we know, abhors a vacuum. Uri Sarid, RAML Work Group Originally posted to Wired’s Innovation Insights