Many articles have been written on how to design stellar APIs that can scale well, conform to all up-to-date standards and use the most cutting-edge technology possible to deliver high-quality access to third party developers. Yet, almost all of these articles tend to completely forget about the fact that you’re building a product for an end-user, who in this case happens to be a developer. Some of them mention that you’re building for developers, but still fail to follow the process of building a product.

To some people, the idea of designing and building something in a vacuum sounds really exciting: You do not have to do any user research; you don’t have to listen to other people. You can finally apply what you learned in school without anything getting in the way. How fantastic is that? Just take whatever requirements and build based on standards.

The reality however, is different. API Design is just as important and just as product driven as any other consumer facing product. Your end-users are going to be other developers, but that doesn’t change the importance of doing user research. You want to build a platform that’s easy to use and will bring the most value to your third party developers.

Proof of concept

Just like with any other product, when creating a new API there is a leap-of-faith assumption. Developer X needs Y to get to Z. Not realizing what your leap of faith assumption is can lead to a lot of unintended, undesired consequences and a lot of tears about how much work has been wasted. Just like when building a product, a POC can really help save time, effort and consequently money. Do developers want to develop for your platform?

Netflix API Developers,
As Netflix continues to grow internationally, the emphasis of our engineering efforts is to satisfy a growing member base and a growing number of devices. To better focus our efforts and to align them with the needs of our global member base, we will be retiring the public API program. Effective on November 14, 2014, public API developers will no longer be able to access Netflix content. All requests to the public API will return 404 errors.
Thank you to for participating in the ecosystem throughout the years.
Daniel Jacobson
VP of Edge Engineering

This is an example of where a simple POC could have done its magic. Sometimes, third parties might not be interested in your data necessarily, because your data is highly coupled with your main product and therefore investing in an API that exposes that data doesn’t make sense.

Functional Design and Documentation

The design of the API should revolve around your third-party developers’ needs. A good POC should have one or more use cases in mind where it returns mock data, while the documentation is done as if the API was completed. You can get a lot of input in this stage to incrementally make your API a lot better.

Language agnostic vs. language specific

The bitter reality out there is that most organizations cannot afford to create a high-quality REST API and provide native support in multiple other languages to begin with, so answering this question is one of the first things an API designer should do before going further. Thankfully, user research comes in handy again. You don’t have to answer this question alone: If 80% of your third party developers primarily use python, it’s probably a good idea to provide a python package to interface with your main product vs. providing a REST API. On the other hand, if your market is does not have a clear preference over what language they like best, it might make more sense to create a solid REST API first. (In either case you have to create a Web API if you’re providing a web service, the discussion is about where do you focus most of your effort to generate most value early on) This approach provides an easy-to-follow roadmap about where to focus your development energy efficiently.

Scalability focus

“We don’t know how many users are going to be hitting our API, but let’s try 10 requests per second” If you’ve ever said this sentence, you weren’t following lean principles. By doing market research properly, you can gauge how often and how many developers are going to use your API. Estimating with no basis is going to lead to one of the two possible outcomes: 1. Complete waste of resources: We designed and optimized the API to withstand an insane amount of traffic, but we’re only getting 1/10 of what we expected or 2. There’s way too much traffic, we have to either optimize our code which will take time, or have to auto-scale which might be more costly than we though initially. As an API performance tester, answering the question of what the traffic is going to look like is of critical importance.

We would all like to write the most efficient, scalable code, but just like everything else, it requires resources, time and effort. I believe talking about scalability in terms of scarcity is a really big topic which requires a separate article, but at a bare minimum: know what to expect from your audience.

API Product Cycle and Versioning

Just like any other product, an API should go through the lean cycle: Learn-Measure-Build. Unless you’re developing for organizations with code that changes only once in 10 years, the market is a very dynamic place. Needs are constantly shifting and your APIs need to keep up with that. That’s why this is a process that needs to constantly happen. If this is done properly, your APIs will most likely end up returning different responses and that’s where API versioning comes in. There are a lot of articles out there that talk about this exactly and there are different ways to do it, so I’m not going to pick sides, as long as this capability is provided. Depending on how long your product cycles are, what your resources available are and what your customers need you may want to support more or fewer different versions of your API.

Build

After you’ve gone through the Learn and Measure phases, it finally comes down to building! You’ve finally learned the root causes of your customers’ problems and now you have to solve them.

There are thousands of books and articles written on this topic, so I’m not going to pretend I can do better than people with decades of experience on this topic. Below I’m going to provide some resources to learn more about the “lean” movement and what I think is one of the most comprehensive guides in designing a REST API.

The Lean Startup: http://theleanstartup.com/

REST API Design: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api