This is the second of two articles on the growing trend of API-first design. In this article Uri Sarid, CTO of MuleSoft (parent to ProgrammableWeb), discusses the approaches to API-first design. He touches on the value of this approach and how it allows businesses to optimize for a great API instead of having the API simply be a reflection of existing code. Previously, Patricio Robles explored real-world examples that illustrate why API-first design is an emerging trend.
How are APIs being developed today?
People’s approaches to developing APIs can be classified in two ways: One is that you implement the APIs or you implement some code and some service, and then you decide to open it up by creating an API on top of it. There are many ways to do that, but the API kind of emerges or is an artifact of your code and your software. The other method is to start by designing the API itself before you implement it, and then after you have designed it the way you want it, you actually go in and create the implementation that exposes the API that you have designed.
Is one method more common than another right now?
I think it’s fair to say that most people today do the former. It’s more natural to sit down and write code, and in many cases you already have the code and you’re just building an API on top of it. But I think there is a growing realization that starting from a design--especially if you don’t already have an implementation--has a lot of advantages.
You’ve called this an “API-first” approach. What are some specific benefits to this methodology?
The value of an API-first approach is something that I have learned the hard way in many companies and engagements that I have had in the past: If you don’t know what your API needs to be, you will end up with whatever API you happen to build, and you're betting a lot on its happening to be good enough.
I think the most classic case is you have some internal application—maybe it has a certain data model, maybe it has a certain way of thinking about the world—and then you do what you need to do to open it up and expose it as an API. What will happen then is that the API will reflect whatever internal structure you have and whatever internal constraints there are.
As soon as you open it up as an API, the consumers of that API--the developers who attach to that API--will end up attaching and relying upon your internal implementation, your internal data model, and so on. That’s great, if that happened to be exactly the way that you wanted them to attach to you. But you lose the freedom to change your internal model after that--especially if your internal model wasn’t really the way that you wanted it to be. That’s one reason why there should be some thought PUT into the API itself instead of having it just be an artifact of your internal development.
Should companies be thinking about API development in a whole different way, then?
There is a growing realization that an API should be regarded as a product itself. Especially if you have external consumers--but for many enterprises even internal consumers of that API--that API is the product. It’s the face that your consumers see; it’s the dependency they have on you; it’s effectively your brand. If that API is easy to use, if that API reflects the value that you’re adding, if it’s very clean, then developers are much more likely to be successful with it—and, presumably, that’s why you created the API to begin with.
It only seems logical that you would want to actually put effort into designing the API and make sure that the thing that you optimize for is a great API, rather than just an easy reflection of the code you’ve already written.
From what you are saying, it seems that the importance of APIs to the business is growing.
We’ve seen time and again where the API is transformative. There’s a growing realization that an API is a business construct as much as it’s a technical construct: A business decides that it can gain significant competitive advantages, significant growth in the marketplace, by opening itself up to other applications, other users, other people whose creativity can be reflected on top of the service that you provide. If you provide, say, a shipping service, you can be the destination site for anybody that wants to ship. But if you open up yourself as an API, then other people who want to embed a shipping capability into their workflow can integrate you in. All of a sudden, you’ve expanded your potential market dramatically.
Is the idea behind the API-first model new?
We’ve already been to this party before. In the past, for example, user interfaces were just kind of auto-generated off of internal code. It used to be that you would take your internal code—maybe it was an old legacy database or something like that--and you would use applications that would expose that as forms.
People haven’t done that for years. What people do today is they start with the User Interface. In fact, they’ll design first the kind of experience that they want their users to have and then go back and implement the application underneath that.
We think the same thing should be done for APIs: You should start with this thing we’ve termed the APX—the experience you want your consuming developers to have--and then design the API with them in mind. Once you’ve got that design, then you go and create the implementation behind it. You actually fulfill the promise that you have made to developers—that this is the clean API that they will have.
How does all of this fit in with the agile development model?
More and more shops are moving toward an agile development process where you don’t lock down everything at the beginning. You have a first pass and then you iterate quickly--deliver something and GET feedback on it. You iterate some more until you get it locked down. APIs present a special challenge there because, almost by definition, they introduce long-lasting, inelastic dependencies that prevent frequent changes once the APIs go live.
A user interface can be iterated quite quickly, and humans are pretty good at adjusting to it: For example, when you wake up one morning and Facebook has introduced a new feature, usually it doesn’t completely break your ability to use Facebook. You might notice it; you might not notice it. Computers are a little bit more fickle about this kind of thing. If you change the API on them, they will tend to just stop and raise their hands and say, “I don’t know what to do here! It’s a little bit different than what I expected.”
There are ways to make API evolution a little bit more robust, a little less fragile. However, to a large extent, once your API is out there, once it’s published, your users will grow to depend on it, and you can’t change it very easily. You can version it; you can come up with a new version of your API and keep the old one around for a while. That seems to be a little bit in conflict with an agile approach that has you iterating quickly.
Is there a way that companies can balance the need for a robust API from the get-go with the desire to iterate quickly?
I think one of the keys to solving this is to make sure at the API design phase you can be as agile as needed, and get the feedback you need, before you lock down a long-lasting version and implement it. To that extent, what we’re doing here at MuleSoft and with our partners on RAML [RESTful API Modeling Language] is to make sure you can iterate on that design very quickly and even mock the service up very quickly and get your feedback before you sit down and have to build a lot of implementations. I think that’s a way to bridge the gap between the need to protect and preserve APIs for a long period of time and the need to iterate quickly until you get the API design right.
I don’t think we have to disrupt the agile approach so much as we have to embrace it and understand how it applies to the API world.
Guest author Meg Cater is a writer/editor and technical content manager for SmartBear Software with a journalism and digital media background. Her work highlights the broader impact of emerging technologies and innovative ideas in the software development and testing space.