Why can API-First improve an API?
By
Nicolas TakashiView All Posts
Passionate about software engineering, good food, and trips around the world using my Yeezy boost 700 v2.
Top Stories
1 - Why can API-First improve an API?
APIs have been in the software industry for nearly 20 years, and during this time, we could test different technologies and principles to develop APIs. In mid-2010 REST APIs were consolidated and became a standard to deliver APIs.
Since the beginning, developers have cared about API Design and how to deliver a better experience for those who are consuming their APIs. And a few years ago, we started to hear about the API-First approach.
So today, I will talk about how API-First could help you enhance your API Design and the developer experience during their consumption.
One thing that many organizations don't know is: Developing an API is hard, and it requires long meetings with stakeholders, choosing the technology stack and much more. An API can be your business’s best friend if you take care of it, but if you don't, you can have a great enemy. A bad developer experience while using your API is enough to create an endless queue of support tickets and a bad reputation in the software community.
Many people think that API Design means to write the code in a way that is aesthetically appealing. But designing an API involves much more than that. API Design means that you will deliver a better experience to the consumers of your API and provide them with a better understanding of how to use your API. There are a bunch of practices to help you improve your API Design, but for now, let's just go through some of the benefits that API Design offers:
But to keep the agility, the quality must be ensured, and developers must take care of the client experience during API consumption. A well-designed API allows companies to improve their development ecosystem, to innovate and build apps that look good and work well across all devices.
Companies like Farfetch, Netflix and Uber are using the API-First approach to provide an improved user experience for their customers.
API-First and their Benefits
Developers are the APIs customers and we want to ensure that they have an excellent experience while using the API, so we use an API-First approach.
What's API Design?
First things first, before we talk about API-First and its benefits, we need to understand what API Design means and why it's important. After smartphones became a reality, and with the exponential growth of social media, many organizations have realized the importance of API Design to their business growth.
One thing that many organizations don't know is: Developing an API is hard, and it requires long meetings with stakeholders, choosing the technology stack and much more. An API can be your business’s best friend if you take care of it, but if you don't, you can have a great enemy. A bad developer experience while using your API is enough to create an endless queue of support tickets and a bad reputation in the software community.
Many people think that API Design means to write the code in a way that is aesthetically appealing. But designing an API involves much more than that. API Design means that you will deliver a better experience to the consumers of your API and provide them with a better understanding of how to use your API. There are a bunch of practices to help you improve your API Design, but for now, let's just go through some of the benefits that API Design offers:
- Helps in better implementation
- Facilitates incremental development
- Promotes better documentation
- Improves Developer Experience
A good API Design improves the usability of your API, resulting in higher adoption and fewer headaches. Now that we know what an API Design is and the benefits that this approach presents, let's talk about API-First.
What is API-First?
An API-First approach means that for any given API, you will treat it as a First-Class Citizen. This means that your APIs are products that will be consumed by clients, but the clients in this context are web or mobile applications. Like a product provider, you should care about your client’s happiness and user experience while consuming your APIs.When we are talking about an API-First approach, we are thinking about long term design and we must listen to customer feedback to help us deliver a consistent and reusable product.
There are a couple of alternatives to delivering an API-First Approach. The most common is to establish a contract for how the API is supposed to behave, by doing so, you will spend more time thinking about the design of the API and how your clients could use it.
API-First and Technology Industry
There are many companies around the world using APIs to connect businesses and create solutions. APIs enable the level of business agility and interconnections demanded by the digital age.
But to keep the agility, the quality must be ensured, and developers must take care of the client experience during API consumption. A well-designed API allows companies to improve their development ecosystem, to innovate and build apps that look good and work well across all devices.
Companies like Farfetch, Netflix and Uber are using the API-First approach to provide an improved user experience for their customers.
API-First and their Benefits
When we talk about API-First, we understand that we want to provide a better experience for our customers, but who are they?
Developers are the APIs customers and we want to ensure that they have an excellent experience while using the API, so we use an API-First approach.
Teams work in parallel
An API-First approach involves establishing a contract between services across an organization, allowing teams to work in parallel. This means that the developers do not have to wait for an API to be published, they can use mock APIs and test API dependencies based on the established API definition.
Improve Developer Experience
As we said before, consumers of APIs are generally developers. So just like User Experience (UX) can make or break the success of a product, the Developer Experience can have the same impact on an API.
API-First helps to deliver a well-designed, consistent and well-documented API ensuring a great developer experience. This way, it's easier to reuse code, onboard developers and reduce the learning curve.
Increases success ratio
Many companies are using APIs in different business processes, from finance and marketing to sales and consumer-facing applications. This means that APIs have a direct impact, either positive or negative, on many parts of the business.
Improves delivery speed
There are many tasks in API development that can be automated using tools that know how to work with an API Definition file and with those files processes such as SDKs, Mocks and API Documentation. All those processes can be auto-generated speeding up the development of APIs and applications.
API-First at Farfetch
Considering that our mission is to be the global technology platform for luxury, we need to provide our partners with APIs that meet the following requirements:
- Easy to understand
- Consistent
- Reliable
- Provide good developer experience
Looking at these requirements and the benefits that the API-First approach delivers to Farfetch, this was a perfect match to achieve the platform goals.
Choosing a specification language
There are two strategies to design APIs using an API-First approach: Code First and Design First.
Design First was the best choice to achieve our goals and to provide automation in our development process.
But we still had the challenge of choosing the appropriate specification language to design the Farfetch APIs.
In the end, this was easy, because there were not many options and we could compare one by one. The requirements were:
- Easy to validate
- Easy to use
- Good community
- Good to automate
Considering these requirements, we opted for the OpenAPI Specification language because there is a large community and a bunch of tools in the market.
How about the existing APIs?
Using API-First for new APIs is easy, but how do you deal with existing APIs?
We cannot rewrite these APIs, so we need to find a way to make them a first-class citizen from the moment we choose to follow an API-First approach.
But wait, the Farfetch platform has existed since 2008. How could we start the API-First approach, when there are a bunch of services running in production environments, keeping our customers and partners happy?
Every Farfetch API already uses swagger to provide documentation, so that helped us, because we created the OpenAPI specification files from the swagger definition. So from this moment, every change in the existing APIs will follow the API-First approach.
API-First benefits at Farfetch
Farfetch already knew the common benefits that the API-First approach provides, but once we started to use it in practice, we found other benefits which helped us to create a solid development process.
Using the API-First approach with a design-first strategy, we could ensure that guidelines to create APIs at Farfetch were followed and we created tools to help us with this job.
Conclusion
Great APIs are part of great teamwork, and it's extremely important that there is an effective collaboration between stakeholders.
A well-designed API will empower your developers to deliver a product that is more consistent, flexible and fast. Always remember that design experience is to APIs what user experience (UX) is to UIs.
Now you know the benefits of the API-First approach and why we decided to follow it. If you want to know more about how Farfetch changed the development process to implement the API-First approach, stay tuned for the second part, where we will talk about how we built our own guidelines, tools to automate validations, and a dedicated team to think about a consumer-facing API.
