How To Design Great APIs With API-First Design

API Economy
Source: Aurionpro

With the spread of open source, we are witnessing the building of an API economy that is based on the principle of developer-first--putting your target developers’ interests ahead of all other considerations when setting out to design a great API. By building on top of APIs that are designed with the developers’ interests at heart, you are able to save you and your developers a lot of work while laying down the building blocks for others to build on top of.

"For creatively lazy developers--as I like to call it--you get to build on someone else’s work. And now there’s a lot of work to actually go and build upon," Mulesoft’s CTO Uri Sarid said referring to the thousands if not millions of open APIs out in the space. "If you work inside enterprises, there are probably thousands and thousands of APIs inside your own enterprise. Whether or not you know about them is something else. And if you look across all enterprises, there’s probably millions of APIs out there. Lots of stuff to go and build upon."

API-first design is about a series of best practices across companies and industries that prioritize a better developer experience ( DX). One way to achieve this is to commit to launching RESTful APIs and by using the RESTful API Markup Language (RAML) to describe them. This article endeavours to teach you what are the pillars of API-first design and how RAML can be a way to achieve it through a user-friendly DX.

API-first drives developer experience

How the API economy is driving much of the total economy

“You can pretty much do anything you can imagine through an API somewhere, regardless of your domain. Regardless of how nichy the thing is or how broad it is, there’s probably multiple providers--which provides you with the kind of competition that you’d like to see out there--and that’s led to a very broad and large set of capabilities, not just for SaaS [Software as a Service] but for anything that has explicit APIs,” Sarid said at an APIcon last year.
APIs used to be simply the technical ways that you achieved something in a business context, but now APIs have transformed into business drivers. Why? Businesses are looking to:

  1. Go mobile.
  2. Discover new revenue streams and models.
  3. Innovate.

APIs empower businesses to do all three, which are all tied to business objectives. This means that the API economy is now much more likely to be funded on a clearly defined schedule, with proper quality assurance testing standards and thorough final Documentation.

This also means APIs are steadily evolving from an extra feature or an upsell to a central product. Salesforce earns half its revenue via APIs, eBay 60 percent, and Expedia a whopping 90 percent, to name a few web-based businesses resting their ROI on top of the API, instead of through their User Interface.

“People are looking at APIs as products that need to be packaged and delivered and documented and they have product managers and so on,” Sarid said.

And this deliberate market shift toward API-first or at least API-priority “drives up the quality and the timeliness of a lot of these API initiatives.”

Four Axioms for Success in the API Economy

There are certain axioms of the API economy and, really, the Web, or even total economy in general, that make the difference between success and failure. Sarid lumped them into four common-sense rules to follow:

API Economy Axiom #1: Fast is better than slow. Enterprises are the slow, fat kids here, but finally even they understand the necessity to bring things to market at least every few months. Agile is more than just a management style--smaller and faster really is better than big and slow.

API Economy Axiom #2: Developers are key decision makers. Whether you are selling them your API and you need to take into account developer experience (DX) or you as a developer are now the key technology decision maker in your company, developers increasingly have a more important voice in the direction business is going.

API Economy Axiom #3: Simplicity rules. Not far off from the first rule of journalism “KISS: Keep It Simple, Stupid,” API design is moving away from complexity and toward simplicity. “The pendulum has swung from SOAP and WSDL all the way over to REST,” Sarid said, talking about how people want to use things they are already familiar with, like HTTP, and will continue to search for other pieces that they can add into it to keep that same level of simplicity.

API Economy Axiom #4: Agile crushes waterfall. Referring back to Axiom #1, it’s no longer about spending two years building huge plans for huge projects. An app needs to be out the door in t-minus six months or it will fail. 

How do you leverage these APIs to be built on top of?

One of the core tenants of API-first design is that the act of designing the API is almost like a clean-room or greenfield exercise whereby existing constraints--like the legacy systems in place and what they’re capable of--should be ignored at the beginning of the API design process. API design should not be constrained by what can be done giving existing limitations, but rather by what should be done. This frees the designer to focus exclusively on the design that best serves the API consumer’s--the developer--needs. Then, later, when it comes time to implement the API, the various stakeholders can decide if the legacy infrastructure can be manipulated to make the optimal API possible, or if compromises must be made to the API design. API-first design is therefore very consumer focused, making sure to define clearly the interface between the infrastructure at the bottom and the API-consuming clients on top, so these two partners can go ahead and start building with an assurance that all three pieces will fit together.

“If you get the core of the API right, if you get the API specification and the design of the API correct, a lot success will flow out of that,” Sarid said, offering steps to get the API “just right” in an efficient manner and timeframe.

API-first Step 1: Plan. Before even starting, you have to decide your purpose and what it really is going to look like.

API-first Step 2: Design and validate. Take a few hours to plan out now, how you are going to make it look and test if it’s feasible. You now should have a tool to make requests against even if you haven’t implemented anything yet. This enables you to work through entire use cases to see how that API will be used.

API-first Step 3: Lock down your Source Code. Nail down what your API spec is going to look like at least for the next month or two based on your plan and design. Automatically generate documentation from that API spec. You now should be able to mock up your API with use cases.

API-first Step 4: Test it all. Then you can generate tests automatically. “Your API is a great testing interface. APIs are pretty much the perfect testing interface. It’s an automated way to access all the functionality. What’s in the API should be accessible. What’s not in the API doesn’t exist.” And, since you’re eating your own dogfood, you can test your API for good DX and consistency across the different pieces that work together.

API-first Step 5: Implement. Let both sides get in and play with it. With all this information, you really start going API-first because clients like iOS and Android understand how to build on top of your API. You can even stub out some of the pieces of the server Framework necessary to implementing an API.

API-first Stage 6: Operate and engage. Put it out there. Engage with your clients. Learn. Then repeat the whole cycle again.

You could also call API-first, DX-first. Every stage of API-first is focused on one goal--delighting your users with an exceptional API experience. Sarid says that you should:

  • Work app-backwards. Ask yourself: What do your users need? Design for that.
  • Focus on modeling cleanly and consistently.
  • Iterate before you implement the API to make sure it works for them.
  • Give the users various tools to discover and play with your API.

The designing of the user interface has all evolved into User Experience because, in a sea of choices, taking UX into account with each step is the only way to stand out.

Be sure to read the next API Design article: How to Tap The Weather Underground’s Plethora of Data Via API