sommai - Fotolia

Manage Learn to apply best practices and optimize your operations.

API design goes beyond integration

Steve Willmott of 3scale answers questions about APIs and encourages designers to have some fun with API design without forgetting about user experience.

APIs are an essential technology that unfortunately presents some design and security problems for developers. At the beginning of the year, Steve Willmott, CEO of API management platform 3scale, made 10 predictions about what would happen with APIs in 2015. We talked with him about some of his predictions.

In part one of this two-part Q&A, we talked with Willmott about why API design is challenging and the issues with making an API public.

What are some of the factors that make API design so challenging?

Steve Willmott: It is, absolutely, I think -- there is a lot more best practice. You would sort of expect, 'Hey, if there's best practice, can't we just read a bunch of textbooks and we'll all be good at this, right? We'll just follow the patents that are established.' You would think that. We think of API design as a very mechanical thing now because developers know how to expose the particular method and have it called. It just seems like a utility. The reality is you are also designing a user experience. You are not designing the user experience for the end user, but you are designing the user experience for the person who is writing code to use your API. In those cases, it matters what the use case is.

Steve Willmott

If the use case is someone is going to get an inventory listing from your site, and then show that to some other customers and make another API call to purchase one of those items, that might be quite different than a use case where they are trying to get the aggregate price change on average overtime or something like that. So, the use cases actually influence the API design, and that means that you kind of need to know more than just the mechanics of, 'Well, how do I create a REST API?' It is a bit counterintuitive.

I think in some way, API design is sort of a mix between Web design and more integration-level technology, and that is what makes it difficult. If it was just the integration part, then I think it would be kind of easy, but the reality is we are also trying to figure out the use cases, which also change over time. So, it is almost like there is an API UX, an API user experience design mode, and we all know how hard that is for websites, let alone for this level. I think that is what makes it hard.

It is like developing open source applications. If you make it public, there are so many eyes on it, and that brings up a lot of criticism and a lot of demand for improvement.

Willmott: You are exactly right. We see a lot of people that are very nervous about their API. They have actually done a pretty good job, but they are like, 'I'm nervous about publishing this because I don't want the guys on Hacker News to tear it apart and say I used the wrong methods." We definitely see that. It is very much like open source because your API is visible and people can criticize it if it is not right.

What topics have we not touched on about APIs that you think are really important for developers and API designers to know about in the coming months?

Willmott: We definitely see APIs becoming central. If you think of HTML5, for example, or mobile, or just partners wanting to integrate, the API keeps coming up as the central point that people need to implement against. That makes it feel like a very heavyweight thing. You have to put in tons and tons of planning and get it right. The thing I would think about if I were a developer, that is kind of a killjoy thing. You want to build stuff and get it out there fast. If you are a developer and you want to start doing APIs or doing them better, I would not be so scared. It is good to get some basics right, like the security. There are tools out there to help you do that.

You can also iterate still. The thing to do if you are iterating on the API and you have third parties using it, try to do that in a sort of a beta phase. Just tell people, 'Hey, use this, but it might break,' and then lock things in later. That kind of gives you some of that agility back. We do find people that are just overwhelmed with, 'Wow, I have to get this API so completely right because I have to support it forever.' It makes it less fun to go to work if you are doing that. I would definitely recommend having some bleeding-edge version of your API that some people can play with that you have messaged very clearly, 'Hey, this might break, but we're moving fast.' That is the thing I would recommend. Just be careful about versioning and things like that. It will work out; have fun with it.

Editor's Note: This Q&A was edited for grammar and style.

Next Steps

API design advice from NetBeans creator

Designing APIs for the cloud

Finding an API design that meets developers' needs

Dig Deeper on API management