How to create an API and power up your business with API-first approach
OVERVIEW
In my first article, I explained what an API is, why you should create an API, what an API-first approach is and why your business should be based on it. In this chapter I will focus on how to create an API and what you should know before you start. I’ll explain what the key principles, design guides and definitions are and how the api-first approach can fundamentally change your business.
Before I begin, I want to make something clear. Today, we should stop thinking about apps in the way we have thought about them before. The applications themselves have become a business. Take the almighty Uber for example. Although people associate Uber with the Uber app, it’s actually an business model that uses an app as a channel to make the business model work. By using the API-first approach, you have taken a step towards preparing your business for the future.
In other words, that means that you should transfer offline models into digital and start thinking as business developer and not application developer. That’s the future of business. To create an API is to think ahead. That’s what the API-first approach is all about.
HOW TO CREATE AN API-FIRST APPROACH
Nowadays, we have a lot of development and specification tools which we can use to develop our digital business on API. They have enabled the launch of a new strategy called API-first approach. API-first approach is strategy for building your business based on data-centric solutionS and approaching it through the exposed endpoints of each resource and over defined channels. Within API–first Approach we have API-design-first Approach which means that it is necessary to make a specification for I/O data for the data-centric solutions, thereby enabling developer experience.
i.e.
You want to build an web application for MVP and later in grow phase you saw that your target audience is coming from mobile devices so you decide to build mobile application.
With API-first Approach you will create API data-centric solution which will power your web application channel. When you want to add mobile application channel, you will be able to do it without any adaption of your data–centric solution. If you developed with API – Design – First Approach, your mobile application developers will be able to start building services to connect on API without any further documentation.
Specification is fundamental for creating API-first solutions.
SPECIFICATIONS
When developing your business with API it is mandatory to have specification before starting the development process. Specifications are used to define every request, response, validation, relations, ACLs, meta etc. which our API will expose to channels.
Before writing a single line of code, you have to be aware of everything API-related. In the other words, developers need to have their development experience defined. Client side developers will know what request they need to send and what response they will receive. Server side developers will know what request they need to validate, allow, deny, authenticate, transform and what response they need to give. Everything is defined before start. Beautiful!
API can be specified with RAML or JSON files. It can be defined according to your own needs and rules. There are also some standards in industry and I strongly recommend using them.
The industry leader for this is Swagger and, as of January 1st , 2016 Swagger Specification has been donated to the Open API Initiative ( OAI ). Swagger offers a various set of tools which provides event better experience. Once specification is defined, it will generate you interactive UI console to test your data – centric solution. Here is the live example: http://petstore.swagger.io/
API DESIGN GUIDE
API design guides are fundamentals of communication between channels and your data–centric solutions. They determine the endpoints for each resource exposed over your API. A resource can be collection of objects, single resource or custom action on resource. For each type of resource we have already some industry standards in regards to API designs.
i.e.
We have an online store where we have buyers who can access their orders. Let’s design our API.
Every resource in design guide must be plural. That means our two resources will be Buyers and Orders. Resources are linked through relationships. In this example we will link Buyers with One To Many Relationship and we will say that Orders belong to Buyers.
This means that single Buyers resources can have many Orders BUT Orders resource will always belong to single Buyers. ( please do not get confused because of plural. )
The best practice of designing this case for API is following:
- Every resource endpoint needs to start with its name:
/{resource} = /buyers
- Every resource relationship needs to be accessed over resource endpoint:
/{resource}/:id/{relation}/:fk
This is how our API endpoints will look like:
GET /buyers – get list of all buyers
POST /buyers – create new buyer
GET /buyers/:id – get single buyer
PUT /buyers/:id – update buyer
DELETE /buyers/:id – delete buyer
GET /buyers/:id/orders – get the list of all buyers orders
POST /buyers/:id/orders – create new buyer order
GET /buyers/:id/orders/:fk – get single buyer order
PUT /buyers/:id/orders/:fk – get single buyer order
DELETE /buyers/:id/orders/:fk – get single buyer order
In this design, :id is the unique ID for resource and :fk is unique key of relationship with which resources are connected.
I will not get deep into API design at this stage but you can start research with following online documentations:
https://geemus.gitbooks.io/http-api-design/content/en/index.html
https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf
MOVING FORWARD
Before I start with more complex things like ACL and Security I strongly checking out the links I have provided. I will cover everything and get involved into every detail of API development but first we need to know how to start and understand the concept behind API development and that concept is at the core of every digital business.
In modern business, it doesn’t matter what will you do. It matters how you are you going to do it and how will you interact with other businesses. I know how I am going to do that – by using API. That’s why you should start thinking about how to create an API.
