Over a million developers have joined DZone.

The Path to a Successful API

There are a lot of advantages to having APIs. In this article, Keshav Vasudevan provides the dos and don'ts of API building - in terms of both public and internal APIs.

Build APIs from SQL and NoSQL or Salesforce data sources in seconds. Read the Creating REST APIs white paper, brought to you in partnership with CA Technologies.

While APIs have existed for over 50 years, they’ve only gone mainstream in the last decade or so, with a lot of buzz and interest around the technology.

There are a lot of advantages to having APIs, both public-facing and internal. However, various organizations and teams still struggle and face issues when embarking on the journey to a successful API.

I recently sat down with Chris Busse, CTO of APIvista to talk more about APIs and how organizations should think about APIs. APIvista is an API-focused development and managed services company that helps clients deliver new business value with APIs. With 20+ years in the IT industry, Chris offered valuable insights into how companies and organization should approach their API strategy.

Building a Successful API

According to Chris, a successful API needs to treated with the same care and attention as any first class product in a company’s portfolio.

“Understanding and having that real product management empathy for your API-consuming developer, the same way you would with any customer, goes a long way in engineering a great API for adoption.”

Applying product management principles and practices when dealing with APIs is the first step to treating your APIs as first-class products. Product managers know their end customers. The same applies to APIs.

Understanding the needs of the API’s end consumer and learning how the API fits into their software development lifecycle is essential to building a solid API. Taking the end consumer’s needs into account during every stage of the API development and deployment lifecycle will help steer the API’s development in the right direction.

Then, there’s the user experience empathy. Designing the API and the artifacts and services around it, with an intention to reduce the learning curve for the intended consumers, should always be a top priority.

Building APIs with the end user in mind is the foundation of the design-thinking approach. Design thinking tries to find a balance between the end consumers, business, and the technology.

The same applies to APIs, and ideally, a well-designed API finds this optimal balance. This would mean that the business value is derived and driven by increased API usage and that the technologies implemented are free of errors and compliant with accepted standards.

With the right balance of product management and user experience principles, the end consumers have an easy time adopting and using the API. Like any product, adoption begets adoption.

Chris believes that this is especially true for public APIs. We see that a lot of times, the community steps up and contributes to the adoption of the APIs if they obtain a lot of value from them, from building documentation to developing client SDKs.

Is Speed to Market a Consideration?

It’s important to have a good estimate on your release date. Very often, there’s a trade-off between speed to market and consistency in design for APIs. While speed to market is important, it should not lead to an inefficient and poorly designed first release of an API.

To this end, Chris recommends identifying a few initial, target consumers and getting their feedback as much as possible during the development phases of the API. This will allow for a good first release of the API while still meeting release deadlines. There is no scarcity of innovative ways of collecting user feedback, from organizing hackathons to identifying pilot customers.

Mistakes to Watch Out For

One common mistake that occurs with this strategy is that organizations tailor their API solely to the needs of these initial customers with the hope that the API would have commonalities that would cater to the market at large. What turns out to be the case, however, are these commonalities lead to more differences.

Thus, an open-ended outlook towards the feedback of these initial customers is recommended. Having a concrete versioning strategy in place can also help overcome this.

According to Chris, “Organizations need to come up with a solid plan on when and how they would add new changes to their API, thus catering to a larger segment of their end consumers over time.” 

Time to market can take a toll if there’s an ideal the organization wishes to follow. Let’s take the example of a hypermedia API, which is a new level of standard in APIs. While there’s a lot of goodness that can come from publishing a hypermedia-based API, organizations need to be absolutely sure that the end customer has the maturity and the expertise to be able to consume these APIs. Remember that by adopting new standards, the publishers are also expecting a certain level of savviness from their end consumer.

Chris explains, “While they may have a technical, or cutting-edge product in the social space, or the digital user experience space, some of them have had a long journey and may still on that journey to raising their API up to being a first-class citizen product.”

When to Adopt the “Design-First” Approach

Design first makes sense if the organization is mature enough to go ahead with the idea. As Chris explains, there have been a lot of cases when a design of an API was proposed and decided on, the development of the API was started, but the design was updated while the development took place.

This is not an isolated case and can happen quite frequently if the communication among various teams isn’t strong enough. This drift can only increase the team’s workload, and in some cases, lead to a lot of frustration, animosity, and mistrust among teams. 

If teams are offering the API’s design up for the development teams to get a head start on implementing the API, they need to have an open line of communication with them, and a lot of trust needs to exist.  Hence, while description formats like the OpenAPI Specification (formerly known as the Swagger Specification), RAML, and API Blueprint serve a really good need, approaching development as design first or code first needs more thought. So, it’s important to go through the API journey and figure out which approach fits your development teams, as an ideal on paper isn’t always the best in practice.

Chris reiterated the importance of design consistency. Regardless of the approach to building the APIs, different APIs for different products and services under the organization should have the same internal guidelines. The  end developer should feel that all the APIs offered by the organization were built by the same organization. This holds true even if these APIs do not interact with each other.

For example, a company like Google, with APIs for multiple, unrelated products like YouTube, Google+ and Google Maps, could still follow some set internal standards that help developers easily adapt to their APIs. This consistency of presentation is something which Chris recommends to all his clients.

Measuring Success

One of the challenges with an API investment is the realization that the ROI can be intangible initially. The success of an API investment can be measured by how often an organization gets repeat business, the frequency in contract renewal, and the amount of popularity the organization’s products and services receive. All of this naturally leads to growth and revenue, and very often, in hindsight, executives realize it was due to the company’s investment in treating APIs as first class products.

Another good measure of success is user adoption. A lot of time needs to be spent on the consumer experience of your APIs. One of the things which Chris and his team measure is time to “hello world”. This is the time that it takes for an end consumer of an API to make a successful call. The better the documentation and code samples, the lesser the time required for the end user to authenticate and call the API.

Setting the Right Expectations

It is important for organizations to realize that consuming their published API involves cost and effort from the customer’s side as well. These APIs will also be competing for the customer’s resources with other APIs and product that expose similar services. So having the expectation that users will automatically start using your API once it’s built is not the right approach.

Like any product, an API will take time and effort to reach its target audience. Time to adopt for APIs is longer than what a lot of people think it is for APIs, and even the most successful APIs took 3-5 years to achieve their level of popularity. Both from getting the adoption, and then committing to the support and the maintenance of the APIs, there is a total cost of ownership for various phases of the APIs, and a long road ahead to achieve the right success.

In Chris’s words, “Different companies may be in different stages of their API lifecycle, and expecting them to reach the finish line with the same momentum is not pragmatic.”

At the end of the day, every API is trying to solve a pain point for the end consumer. Tying the value attribution to the pain point, and the solution that the API is providing, is what is ultimately going to make it successful, both at the technical and business level.

The Future of APIs

Chris feels that the interface which humans use to interact with machines will fade to the background, and the computing will become both as ubiquitous and invisible. We’ve already seen the interface evolve significantly for the past decades, from the gigantic boxes of the first computer to the seven-inch display of the iPhones we carry in our pockets. The same could hold true for APIs, with better and interesting interfaces that evolve for end developers to consume them. 

Interested in Learning More?

Chris Busse is presenting this week at The API Strategy and Practice Conference (APIStrat) in Boston, MA. Learn more. 

Follow Chris Busse on Twitter as he shares his thoughts on the API space.

If you’re interested in learning more about APIvista, check out their website here.    

The Integration Zone is brought to you in partnership with CA Technologies.  Use CA Live API Creator to quickly create complete application backends, with secure APIs and robust application logic, in an easy to use interface.

Topics:
api design ,integration ,building apis

Published at DZone with permission of Keshav Vasudevan, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}