The acronym API has come a long way. In 1980, asking about an API meant building something for a massive corporate software package. In the 1990s it meant building with the tools for a 3D card or a sound card. Today, however, the term tends to mean just one thing: RESTful Web APIs.

And what we now call APIs have grown to encompass all forms of interfaces from all manner of places. From Google Maps to payment APIs to deep research APIs from MasterCard that allow developers to discern restaurant hours by credit card transaction timestamps, APIs are everywhere.

But this is a buzzword that has taken on loads that could not be fully born by other buzzwords. “APIs in enterprises” could easily be replaced with “SOA in enterprises.” Even before SOA, during the original dot-com boom, the term B2B took hold as a metaphor for building a software company that, today, would be an API provider.

Why did it happen? Look to REST. Look to AJAX. Look to the explosion of data and the realization by enterprises that keeping their data locked away from customers isn’t always a good idea. Whatever the reason, API management is now the name of the game, and that game is filled with hidden gotchas.

There is hope, however. The future of API management is bright and filled with best practices, better processes, and lots of Swagger.

What to offer
Just as in the days of SOA, your company has data that it would like to offer to the world at large. But what data should you be offering? What do your customers want to consume? Those are tough questions that need to be asked right at the start. And the answers aren’t always found immediately; it takes time and agility to get it right.

Seb Taveau, senior business leader and chief developer evangelist for MasterCard’s Open API, explained how this process worked for MasterCard as it figured out how to make its data available to the public—no small task for a privacy and security fortress of a company.

“MasterCard had been working on taking some of its private APIs and making them public for the past four years,” he said. “APIs became key for MasterCard about a year ago. They wanted to make sure MasterCard was a tech companion, not just a payment network.”

And therein lies the key to finding a good starting point for building an API: a clear business goal, preferably one that keeps developers at the forefront.

“The team was built and new management was put onboard,” said Taveau. “The background of most of the team comes from the technology world, hardware and engineering, software architecture… There are a lot of different profiles from very well-known tech companies,” he said, highlighting another key to API success: diversity of technological skills on the team developing the API.

“We started looking at the developer.mastercard.com site and tried to see what content was good, what needed to be reworked, and what we needed to have to make sure we could appease the needs of this non-traditional customer base for MasterCard,” said Taveau. Developers are, after all, the customers of all APIs, and should be treated like any customer, he said. They should be kept happy and be heavily considered when designing a product.

Beginning with existing APIs is another way to quickly get things started, said Taveau. But repurposing previously exclusive APIs has to be done in a way that puts the least amount of friction between you and the developer consuming the data.

“When you work with a large partner, you develop APIs that are kind of one-on-one, private APIs,” he said. “Our goal was really to make sure whatever we published on the website were truly public, open APIs and did not require preexisting relationships with third parties to use them.”

The real heart of the success MasterCard has seen with its open APIs has comes from the fundamental philosophy that underlies the goals of the developers on Taveau’s team. “We see our job as being the voice of the developer inside MasterCard. We define the process to the point that the developer doesn’t have to be a payment expert to implement payment inside an application,” he said.

That sentiment is mirrored by Omar Khan, partner director of program management for Microsoft’s Azure API Management. “A successful API program encompasses developer engagement, business insights, analytics, security and protection,” he wrote in an e-mail to SD Times.

But the APIs don’t stop at payments. MasterCard’s APIs can also be used to find restaurants, discern their open hours, and even to determine if their food is any good. Local customers tend to favor certain joints, after all, and the locals always know where the best food is in any given town. Comparing restaurant receipts with card users’ zip codes yields a listing of the places the locals like to eat, versus those that tourists prefer, or that no one prefers.

The restaurant API is a new one, said Taveau. The local eatery API is “designed for applications to help you when you travel and go to a new city. When you go to a new place, you can pop up OpenTable and see reviews. But what we are doing here is a layer where we can pinpoint, based on our data, if it’s a restaurant preferred by locals or if it’s a tourist trap, based on the zip codes of the customers,” he said.

As a result of offering data that steps outside of the purely monetary realm, MasterCard has succeeded in broadening the appeal of its development APIs. Said Taveau, “What we’ve seen by making them publicly available is, we’ve seen usage outside the usual areas of Master Card. For example, a large carmaker in Europe integrated our location information into their system. They can now tell which gas stations are closed at night [or] which banks close earlier.”

The long haul
Steve Willmott, CEO of 3scale, has been working on API management longer than anyone. 3scale began offering services and products to better help enterprises manage their APIs in 2007. And back then, business was not quite booming.

Today, however, things have changed. “The good news is, what we thought would happen is happening,” he said. “Pretty much everyone has an API or needs an API. They need key infrastructure for that. It took a lot longer than we thought it would back in 2007. eBay had an API back then, and there were starting to be a list of APIs. We weren’t wrong, we were just a little early.”

Though they were pioneers, they fortunately did not fall by the wayside, and 3scale today offers tools that have evolved in lockstep with the enterprises that need them. “The first thing we did was build an API marketplace, but there were so few at the time it was hard to get that critical mass going,” said Willmott.

“We ended up changing a year and half in to focus on providers and the tools they need. Now it’s back to the point where the marketplace makes sense.”

Those tools that enterprises need, said Willmott, are “around having control of the data flow. Because it’s not a website, you don’t get analytics. You really want to know what’s going in and going out. It’s really about that control, and in large organizations that have multiple departments that have APIs, all doing slightly different things, giving you the overview of that traffic is important. You have to put limits in place so no one does anything they shouldn’t.”

Willmott said that another thing that has changed since 2007 is the emergence of de facto standards and frameworks. While there is not a definite leader in this new space, he does have a favorite.

“There are some standards that are emerging to describe REST APIs: Swagger, and the RESTful API Modeling Language (RAML),” said Willmott. “Swagger, which we support and which is the widest adopted, is becoming a blueprint for API design and API patterns. That is important.”

Entering with Swagger
Tony Tam, founder and CEO of Reverb and leader of the Swagger API framework open initiative, said that Swagger began as a specific solution to two problems encountered at Reverb in 2011.

“One, as a member of a small team, I was personally responsible for documenting our APIs,” he said. “When we had a partner paying for a special set of APIs, I’d have to make a special set of documents for that partner. That was really annoying at a company of five people at the time.

“Second, the people who would consume the APIs expected us to deliver an SDK. I had to deal with that, and thought we could come up with a better solution.”

Swagger became a solution to both of these problems by establishing a standard way that RESTful APIs should behave and how they should communicate with developers. “Really, Swagger is a metadata layer or a description of what an API can do and how you use it,” said Tam. “As long as that description is succulent and provides consistent information, you can generate documentation automatically. You can generate clients automatically. You can generate documentation tools and sandboxes. That’s what started it. In 2011, we open-sourced the technology and kept going on our merry way building software for understanding technology.”

It wasn’t until 2012 that people started to pick up on Swagger. Today, it is at version 2.0 and has a massive list of companies inside its working group. “Once it started picking up traction, we realized it was something bigger,” said Tam. “It grew exponentially since then. Since our release, we’ve revised the specification four times. For the last version of the specification, we put together a working group of 500 companies and individuals, from Microsoft to garage startups, to regular people that wanted to participate in the design of Swagger. We put together this large working group and released the most current version in August 2014.

“The idea is really around saying ‘Here’s a way to describe APIs, and it makes everyone’s lives easier when it’s done that way.’ ”

Lorinda Brandon, API evangelist at SmartBear, agreed that Swagger appears to be the current hot topic in API management. However, she said that there’s still a lot of room for innovation and competition in the spaces that Swagger has been growing.

”Swagger is a very interesting player in the whole service description space,” she said. “Swagger 2.0 has a lot of momentum. They have developed this working group, they’re building the next-generation service descriptors based on the input of a lot of players in the industry. They’ve enlisted the help of a lot of high-profile vendors. The result is that there are some interesting things you can do with Swagger you can’t do with the other service descriptions.

“You can see, as the market evolves, all these service description languages starting to blend together. How do you collaborate across functions when designing and developing and iterating on an API? They’re all trying to solve the API as a product problem. There’s a lot of room to grow in there. What we’re starting to see is that all these players came from a different perspective, but they’re all starting to merge a bit. People will start standardizing on one or the other and service descriptors, and a lot of the functionalities will start merging together.”

Tam said that the future of APIs requires tools like Swagger, particularly as the number of RESTful, publicly accessible APIs continues to grow.

“I believe we see now APIs are everywhere, and everything needs an API,” he said. “Your car is going to have an API. The biggest challenges for consumers of APIs, ultimately, is that it’s just hard to connect to all these different styles and structures of services. There has been no standard. The reason why is that standards in the past have tried to solve everyone’s problems. Customer are revenue driven. I think we’re going to see more people moving to description formats because it’s going to be impossible to keep up with writing documentation for their APIs.”