What is an API First definition?

Application Programming Interfaces (APIs) are the interfaces provided on the resources that you want to leverage in the interaction process from your customers, partners, employees, business users, etc. via the application or GUI created on top of it.
That means that your applications or GUI will be as good as your APIs because what you reflect on your UI is what you get from your APIs–at least in modern applications–so it’s really important to have a good design in place for the APIs, that adds:

• Consistency
• Flexibility
• Usability
• Agility
• Performance
• Security

API First definition

API First means different things to different people in an enterprise:

• For CxO level it means that they have to think about investing in a platform that can support the development of APIs, being the top priority.
• For architects, it’s about focusing on the API design first and deciding the catalog of API that will be made available to the developers for building the apps or web pages around it.
• For developers, it’s about how to manipulate the set of APIs and develop the award-winning applications and be the part of the trusted community to provide positive feedback.

So API First design is what we are talking about here, as it’s the core for enabling the digital business. Companies like Netflix, Uber, Twitter, etc. have created the whole new business model powered by great API design and architecture around it because it provides a far better customer experience compared from the traditional software development approach where the heavy customer experience was built first and then the APIs were created to access and manipulate the data.

The design has been an important aspect of everything you build and it applies to the APIs as well. It’s important to have the right design in place up front so that you can understand how your API is going to look like:

• URL format
• Supported Message Format
• Supported Methods
• Custom Headers if any
• Parameters
• Pagination
• Versioning
• Exception management
• Authentication

It’s always good to keep the APIs simple so that the developer can look into the definition and work out what it does without reading much of the documentation. I am not suggesting that you should avoid having the documentation around APIs, what I am trying to say is that APIs should be self-explanatory and consistent across.

Once the API is designed, share it with the team who are the consumers of it and let them try the Mock API to see if they like it or they want to suggest changes. Once it’s finalized move the design to build the API. That’s what API First is all about.

Effective collaboration

Great API’s are part of great teamwork and it’s important that there is an effective collaboration between the producers and consumers of the API as all of them will have a different perspective and will help in designing a great API.

To help you with the API First iterative approach many vendors have come up with the products to support that, for e.g – swagger.io, apiary.io (now part of Oracle), raml.org, etc.
There are multiple API description languages (ADL’s), some of them are very popular (like Swagger) and sort of becoming standard for API’s.
API Transformer, proposed by apimatic, is one online tool that can help you convert one ADL to another and yes at the back of it are APIs.

Once you are done with the design you need to choose a platform to convert the great design into real API’s, there are many vendors with API Management products to help with that and Axway API Management is one of them.

If you are looking to start a Digital Journey then for sure APIs are the starting point and API{1st} is where you start from.
===