idspopd - Fotolia

Get started Bring yourself up to speed with our introductory content.

Why interfaces are an integral part of a successful API design

This is the first installation of a four-part series intended to be an API design decision-making toolkit for enterprise architects.

Ever download a mobile application only to immediately delete it because the user interface wasn't intuitive? Or sat in a new rental car for 5 minutes trying to figure out how to adjust the mirrors, use the turn signals, or even just shift the car out of park? These are examples of how important an interface is. A well-designed interface can make a significant difference, both in perception and in actual usage.

This is the first of a four-part series on API design. While it may be the buzzword du jour, the acronym has been around for a long time, standing for application programming interface. What does that mean? It means an API is the door to information systems for all the other systems outside, both inside and outside a firewall. An API is not a service, but rather the visible portion of a service to the consuming system. An API doesn't have to be REST-based, use URLs, XML, JSON, SOAP, or HTTP. In fact, there are APIs based on TCP/IP sockets and fixed-length messages that do their job very well.

Expectations and pace are changing. Years ago, a standards body could discuss things for months (or years) to finalize fixed-length messages, with companies taking another year or two to implement the systems behind APIs, and no one complained (loudly). Today, that won't cut it. Rather than wait for a standards body, the model is get an API out there and gain adoption as quickly as possible. Even then, the expectation is one of self-service. Users can read documentation, register for access, and begin writing code against an API in a matter of minutes or hours rather than months and years.

It's safe to say the design of APIs is only going to become more important. For a startup, API design may be a mission-critical decision. For an established enterprise, it may not be mission-critical today, but APIs will only become more important to a company.

A well-designed interface can make a significant difference, both in perception and in actual usage.

Poorly designed interfaces will result in frustrated consumers, more expensive integration efforts and possibly even revenue loss. Well-designed interfaces, on the other hand, should result in enabled, satisfied consumers; less expensive integration efforts; and even new revenue through monetization opportunities. Did anyone see the potential revenue boost for Amazon when it took its internal APIs for infrastructure provisioning and exposed them publicly as Amazon Cloud Services?

It is important to know there isn't a silver bullet for API design. If there were, there wouldn't be a need for design, it would simply be an API deployment. Every situation is unique, and each design decision has tradeoffs.

This series will provide a pragmatic toolkit that can be used when you're making API design decisions. There are four key factors:

1. Know your goals

2. Know your consumers

3. Read versus Write

4. Embrace change (versioning)

While it may seem obvious, it's important to have a solid vision for an API. Is concern centered on internal development projects and system integration? Are features being exposed publicly? Is there a goal to monetize APIs, or are they necessary for doing business? What level of investment can be committed to the ongoing evolution of APIs and the systems behind them?

If one concern is internal development and system integration, APIs are going to need to be more expansive. In addition, legacy or commercial systems and their integration capabilities may have limitations. That being said, here are two key pieces of advice:

  • Don't let the limitations of existing systems bleed into an API design, otherwise those chains will never be broken. Don't create glue; create a facade that will enable the interior to be gutted in the future if need be.
  • Treat internal consumers as if they are external consumers. All too often, we take shortcuts because we assume we can just go down the hall and talk to someone, or we just get caught up in other priorities. We may think other teams don't have a choice so we can get away with this, but that's a risky proposition. How many companies' transition to cloud services happened as a result of someone putting Amazon services on their corporate credit card rather than waiting weeks or months for their servers from IT?

Going further, what are the pain points with internal development and system integration today? While most companies can claim areas of significant reuse within their enterprise, is that reuse as optimal as it could be? APIs can have a direct impact on the number of changes that go on within services.

If there is concern about exposing things publicly or externally, APIs have to be thought of as a product. Is there competition? Will be there a charge for access? No matter what, if a company is dealing with consumers outside a firewall, it needs to commit to investing in the effort. The degree to which investments can be made in upkeep will influence design decisions. If that investment is low, API design should enable as much self-service as possible to minimize costs. A higher level of investment may allow for more hands-on interaction.

An API can't be put out there and simply forgotten until someone complains. From a design perspective, one of the first decisions is whether customers or consumers will have a say in it. Companies differentiate themselves through the degree of customization they allow in their offerings, and APIs are no different.

If you're catching up with the competition, there may be a de facto API that needs to be incorporated, although you should make sure to consult the legal department before you adopt a competitor's API carte blanche. From a technology perspective, there is a gravitational pull towards Web-based APIs, but if you're dealing with an established marketplace, there may be legacy approaches and technologies that need to be supported.

Without goals, APIs are going to be heavily influenced by the direction of the winds today. Will the winds be in control, or will the direction be set and the wind's power harnessed? With goals in hand, the next step is to know potential consumers.

About the author:
Todd Biske is an enterprise architect with a Fortune 50 company in the St. Louis metro area. He has had architecture experience in many different verticals, including healthcare, financial services, publishing and manufacturing, over the course of his 20-year career.

Follow us on Twitter at @SearchSOA and like us on Facebook.

Next Steps

How to stay ahead of API trends

Quiz: What do you know about developing APIs?

How to integrate a third party API into an enterprise app

Dig Deeper on API management

Join the conversation


Send me notifications when other members comment.

Please create a username to comment.

Do you think user interfaces are part of a successful API design?

I think that the GUI is but one potential consumer of an API's design.  UI is being fragmented based on the experience.  Web UI vs. Mobile UI, vs. no-UI (here's is about consumers of the API who will mash it up into a composition of new services that might then be front-ended by another uber-API).    So, the real answer to your question is that "it depends".   At the end of the day, the true parties that should have input into API design are the various developers who will be using that service.   Here's where it gets interesting as the developer constituents vary widely in skillsets and preferences:  Web might be a PHP dev, Mobile likely a JS dev using a iOS/Android SDK, the 'no-UI' developer is likely a .net/java dev.   REST abstracts a lot of this, but not the 'context' which is (as you point out) 'king'.