Why Not To Overlook API Planning And What To Do About It

While understanding which type of API you are building is a vital step in creating the perfect one for your company—and one that users will love—it is just as important to carefully plan out your API’s capabilities.

Surprisingly, while being one of the most crucial steps in API development, this step is usually rushed through by companies excited to generate a product map and start working on code.

In many ways, building an API is like building a house. You can say, “I want my house to look like this picture,” but without the blueprints, chances are it isn’t going to turn out exactly the way you had hoped. Yet while we carefully plan and build houses, APIs have been plagued by the “agile methodology.”

While I am a fan of agile and I find it to be one of the greatest advancements in project management, like all good things, it has its time and place. Unlike many Software as a Service applications built for today’s web, an API’s interface is a contract, and as such cannot be constantly changing. With increases in the use of hypertext links and hypermedia, perhaps some day in the future that may no longer be true, but right now many developers are hardcoding resources and actions, and as such changing the resource name, moving it or changing the data properties can be detrimental to their application.

It’s also important to understand that developers won’t just be relying on your API to do cool things—they’ll also be relying on it for their livelihood. When you put out an API, you are giving developers your company’s word, and when you break the API, you are not just breaking your company’s word, you’re undermining their ability to provide for their families. So it’s important that you create a solid foundation for your API, just as you would a house. It’s important that you understand what your API should be able to do, and how it will work. Otherwise, you may lock yourself into a poor design or worse—create an API that doesn’t meet your developers’ needs. If that happens, you’ll find yourself taking a lot more time and spending a lot more money to fix what you should have planned up front instead.

Who is Your API For

As developers, we tend to like to jump to what our API will do before we think about what our API should do, or even what we want it to do. So before we get started, we need to take a step back and ask ourselves, “Who will be using our API?”

Are you building your API for your application’s customers? For their business partners? For third party developers so that your platform can be extended upon? Often times the answer tends to be a combination of the above, but until you understand for whom you are building your API, you aren’t ready to start planning it.

To Which Actions Do They Need Access?

All too often I hear companies say, “We want to build an API to expose our data,” or “We want to build an API to get people using our system.” Those are great goals, but just because we want to do something doesn’t mean we can truly accomplish it without a solid plan.

After all, we all want people to use our APIs, but why should they? While it may seem a little harsh, this is the very next question we need to carefully ask ourselves: Why would our users (as we identified them above) want to use our API? What benefit does it offer them?

Another common mistake is answering the question of “why?” with, “our reputation.” Many companies rely on their name rather than their capabilities. If you want to grow a strong and vibrant developer community, your API has to do something more than just bear your name.

What you should be doing is asking your potential users, “Which actions would you like to be able to accomplish through an API?” By speaking directly to your potential API users, you can skip all the guesswork and instead find out exactly what they are looking for and which actions they want to be able to take within your API, and also isolate your company’s value to them. Often, the actions your users will want are different from the ones you anticipated, and by having this information you can build out your API while testing it for real use cases.

Remember, when building an application for a customer, we sit down either with them or the business owners to understand what it is they want us to build. Why aren’t we doing the same thing with APIs? Why aren’t we sitting down with our customers, the API users, and involving them in the process from day one? After all, doing so can save us a lot of time, money and headaches down the road.

Plus, by asking your users what they want, you may find you have better selling points to get the support from other areas within the business. Most importantly, you can answer the vital question of why you are building the API in the first place.

David Berlind is the editor-in-chief of ProgrammableWeb.com. You can reach him at david.berlind@programmableweb.com. Connect to David on Twitter at @dberlind or on LinkedIn, put him in a Google+ circle, or friend him on Facebook.

Comments