Wednesday, April 01, 2009

API-First Design

I don't pretend to be an architect, but sometimes I wonder if APIs shouldn't be the starting point of product development, rather than an afterthought.

Yesterday, I suggested that if there were such a thing as a middleware API maturity model, "intentional API design" would have to be one of the middle levels. But I think (in fact I know) it's possible to do better than that. It's possible to make API design the sharp edge of the wedge, in software development.

This is not a new concept. Joshua Bloch and others have advocated early design of APIs, rather than letting APIs trail product design (as currently practiced). By early design, I mean that the APIs literally are written first, before the software itself.

A lot of software development happens this way, of course: You draw UML diagrams, identify key interfaces, write mock methods, etc., before writing "real" code. That's fine, but it's not quite the same as defining an API.

API-first design means identifying and/or defining key actors and personas, determining what those actors and personas expect to be able to do with APIs (i.e., what are the possible use-cases, user narratives, or stories that encapsulate the business problems these people need to solve), and -- very important -- trying to understand the mental model each actor brings to the problem space. The mental model will drive architectural and design decisions at various levels (for example, it will suggest what kinds of business objects each user thinks in terms of) and will keep the overall process on a track toward good usability.

It's not necessary to overspecify the API at the outset, the way most products are overspecified at the requirements stage. You can begin writing mock code immediately. The nice thing about writing to an API is that you find out very quickly whether it is serving your needs; you learn where the holes are. That means an API-first design process is, to a degree, self-guiding.

An overspecified API is your enemy. In the end, it will constrain the user in funny ways, and if you use the API as the core of your development, it will constrain your developers, too.

And that brings up the most important reason to consider API-first design, which is that you get a tool for creating the product itself. Your developers end up using the API to write the product. Early API mocks are the basis of unit tests. There's no downstream costs to "adding on" an API later, because it's already core. When the API is finally delivered to customers, its capabilities have been thoroughly tested (by your own R&D team, who used it to build the product).

So at the top level of the (fictional) Middleware API Maturity Model (if such a thing existed), there'd no doubt have to be a nirvana level called "API-driven design," characterized by the well-known Dogfood Pattern (tm), where you consume your own API as part of everything you build. Most vendors practice this to a greater or lesser extent already, but if you start from a strategy of API-first design, the degree of API reuse can be very high indeed.

I know of only a couple of R&D organizations that are aggressively and systematically applying an API-first design methodology right now. I have a feeling the number will grow. It's too good an idea not to.


  1. I agree on some things, however the main goal of APIs (these days I'm not talking about the future) is to open existing technologies to gain a wider market and community.

    However, as an API provider firm we have seen a few cases where the API is thought before the product even exists, but the API design phase itself is completely independent from specification phase.

    Put it that way, we see API development exactly as any application development. It has to be architectured, it has to bring a solution to a problem and first and foremost it must either create or adapt to existing technology.

    API-First is a great idea, but unfortunately it doesn't apply to all the web apps out there just yet, I do think though that in a few years, API-First development will be a usual pattern itself.

    For for instance we designed the API for what we needed to do, then made the frontend use the API for anything being done. Much easier to track problems and provides a much stronger API for third party developers using it considering that we are using it ourselves and have to fix bugs when they do happen.

    Hmm, basically what I'm saying is that API-First is a great concept, but doesn't apply to half of the web apps out there -- just yet :)

  2. It's a nice idea because it enforces and encapsulates a number of other good principles - explicit is better than implicit, the MVC segregation of data, look'n'feel, and user interface, the object oriented principle that two objects with the same interfaces to others should be equivalent. An API, after all, should describe all the inputs and outputs of your application in a suitably structured format.

  3. "API First" is spot-on - the way we at Mashery describe it is that a developer should be able to build any or all functionality of your website through your API, and that your web app actually runs on the same APIs (and therefore the same codebase) that you make available to third party developers.

    The advantages of this approach are obvious:

    - a single codebase to maintain

    - no additional work to open the API (through Mashery, of course :) - since you will need to create rules around which developers are authorized to use which API methods if all services are built as APIs)

    - consistent behavior across the API and the web app. I have seen search APIs that return different results for the same search depending on whether that search comes in through the API or the web page; this makes developing apps difficult, since you can't test and debug different searches on the website.

    - by opening the full set of services through APIs, you are providing the broadest possible toolset for third party developers to use in building apps, and you will see way more innovation than if you limit your APIs to a subset of services.

    So even if it is too late to be "API First", we strongly recommend that you "Open Everything" as quickly as you can, even if doing so takes time. The New York Times is setting a great example of how this is done - since opening their first API last October (campaign finance data), they have steadily opened more and more services over the past few months, and will continue doing so until everything is open. They have publicly announced their commitment to opening everything, so developers know that there will be new and exciting building blocks coming down the road.

    Oren Michels

  4. Anonymous11:37 AM

    If web 2.0 is truly about mashups and partnering, the API must be considered first. I know some intiatives that are buildinig their platforms this way. The goal is to build a feature-rich api set and expose the UI elements over time (and in some cases, never).

    Great blog, I'll be watching more.

  5. Anonymous8:37 AM

    Great post and good points. Newer iterations of development frameworks like Ruby/Rails are also likely to help since they "encourage" you to think about structuring your applications in a restful way from the beginning.

    Also I'd add that we're starting to see companies whose core value is actually their API - and their website is documentation and promotion.

    Even if core business is end user focused though it's increasingly likely that pretty much any app which is either content driven, has social elements or delivers something that can be used as infrastructure elsewhere will get a lot of value out of putting out an API so it makes sense to plan for this from the beginning.

    Steven Willmott / 3scale

  6. I found this through google after I was thinking the same thing and wondering if it had a name, but now that I read your post, I also realize it's exactly why object-oriented programming was invented.

    What you're basically describing is just object-oriented design, with encapsulation, abstraction, modularity, etc.

    Just as when you think about your data as objects with predefined methods and accessibility options, you do in an API. In OO, your dogs don't starve as you use your own methods to access the data.

    The difference here is that you're just treating your products as objects.

    1. Anonymous6:38 PM

      It's a bit too much simplification comparing API-first with OO. OO is also about e.g. inheritance, a thing not occuring in APIs in a comparable way. API-first is simply a good approach, that is valid for many fields, not just OO.
      You can be purely functional without any state in your program ("OO-ish") and still is API-first a very good approach imo.
      Also API is a very data-driven approach, while OO is very object-driven. In OO you don't handle data, you handle objects and their methods (which then handle that data). In an API, you're usually directly interacting with data.

  7. Designing is an Excellent talent. Nice and awesome post. Thanks for that. I know about a concern who have excellent experts for Graphic designs. They are the one Vane Technologies, who helped me out to design my office website.

  8. This blog is very useful for me. the content is full of meaning and the blog template is so cool.
    ed hardy perfume
    vera wang perfume
    calvin klein perfume
    paris hilton perfume

  9. Hey Guys !

    USA Fresh & Verified SSN Leads AVAILABLE with best connectivity
    All Leads have genuine & valid information

    First Name | Last Name | SSN | Dob | DL Number |Address | State | City | Zip | Phone Number | Account Number | Bank NAME

    *Price for SSN lead $2
    *You can ask for sample before any deal
    *If anyone buy in bulk, we can negotiate
    *Sampling is just for serious buyers

    ->$5 PER EACH

    ->Hope for the long term deal
    ->Interested buyers will be welcome

    **Contact 24/7**
    Whatsapp > +923172721122
    Email >
    Telegram > @leadsupplier
    ICQ > 752822040


Add a comment. Registration required because trolls.