An API-First Development Approach

regardless of the type of application that you’re developing, chances are that if you’re developing for the cloud, then your ultimate goal is to have that application be a participant in an ecosystem of services. in that case, i would take a look at the concept of an api-first approach.

why rest apis?

the api economy is growing rapidly and companies are joining the fray in making apis an integral part of their growth strategies.

tech giants like apple and google are gearing towards an api-centric future. the surfacing of new interconnected hardware, wearables, and soon driverless cars shows how important apis are in our lives.

what is api-first?

a lot of companies start with building web or mobile applications, and only then as a side project they build an api for third party companies or for integration purposes. they see it then as two channels: one web or mobile channel and one api channel. the problem with this approach is that it results in an artificial api that wasn't properly built and tested during design.

a better approach is to build the api first and build your web or mobile applications on top of that api. this forces you to design an api and use it for your own app so that it's a more real-world and developer-friendly rest api.

api-first development is a strategy in which the first order of business is to develop an api that puts your target developer’s interests first and then build the product on top of it (be it a website, mobile application, or a saas software). by building on top of apis with developers in mind, you and your developers are saving a lot of work while laying down the foundations for others to build on.

to simplify, think about it like this: you are building cloud-native applications. after code gets checked into your repository, tests are automatically run and you have release candidates running in a lab environment within minutes. the world is a beautiful place, and your test environment is populated by rainbows and unicorns.

now, another team in your organization starts building services with which your code interacts. then, another team sees how much fun you’re all having, and they get on board and bring their services. soon, you have multiple teams all building services with horizontal dependencies that are all on a different release cadence.

what can happen if no discipline is applied to this is a nightmare of integration failures.

to avoid these integration failures and to formally recognize your api as a first-class artifact of the development process, api-first gives teams the ability to work against each other’s public contracts without interfering with internal development processes.

even if you’re not planning on building a service as part of a larger ecosystem, the discipline of starting all of your development at the api level still pays enough dividends to make it worth your time.

why api-first development?

a development process is currently not parallel, but synchronous.

once a new service or a new feature is in a need for development, the r&d teams are starting to work on the design. once done, the backend team is starting to write a prototype (other teams like frontend and q&a are waiting). once the prototype is done, an api document can be prepared and shared with the different teams (q&a, frontend).

when change is needed because of a feature, bug, improvement, or enhancement, this cycle will begin again, wasting valuable development time and decreasing time-to-market for the new service.

as you can see in the picture above, first, the back-end team is starting to develop and implement a new api. second, the api is being given to the front-end teams and testers for using and testing it. third, the front-end teams and testers are building sdks, tests, and more to interact with the api. this is synchronous development.

api-first development will allow parallel development by all teams without the need to wait for changes to be released by one team or another.

in the picture above, we can see the first the apis that are created are mocks. second, both back-end, front-end, and test teams are starting to work with the mocked apis. once the api is ready, all teams can switch to the production or staging api. this saves a lot of development time.

restcase provides mocking, debugging, automatic documentation and testing tools for apis, with team notifications and sharing across all the design & development stages, and enables you to work in a collaborative api-first approach.

building services api-first

these days, the concept of mobile first is gaining a lot of traction. it refers to the notion that from the very beginning of your project, everything you do revolves around the idea that what you are building is a product to be consumed by mobile devices. similarly, api-first means that what you are building is an api to be consumed by client applications and services.

cloud-native is more than just a list of rules or guidelines. it is a philosophy and, for some of us, a way of life. as such, there are guidelines for cloud-native that might not necessarily map to specific physical requirements imposed by the cloud but that are vitally important to the habits of people and organizations building modern applications that will be ready for future changes to the cloud landscape.

built into every decision you make and every line of code you write is the notion that every functional requirement of your application will be met through the consumption of an api. even a user interface, be it web or mobile, is really nothing more than a consumer of an api.

by designing your api first, you are able to facilitate discussion with your stakeholders (your internal team, customers, or possibly other teams within your organization who want to consume your api) well before you might have coded yourself past the point of no return. this collaboration then allows you to build user stories, mock your api, and generate documentation that can be used to further socialize the intent and functionality of the service you’re building.

all of this can be done to vet (and test!) your direction and plans without investing too much in the plumbing that supports a given api.

these days, you’ll find that there are myriad tools and standards to support api-first development. there is a standard format for api specification that uses a markdown-like syntax called api blueprint or swagger . these formats can be used by code to generate documentation and even rest api server mocks , which are invaluable in testing service ecosystems.

in other words, there is absolutely no excuse for claiming that api-first is a difficult or unsupported path. this is a pattern that can be applied to non-cloud software development, but it is particularly well-suited to cloud development in its ability to allow rapid prototyping, support a services ecosystem, and facilitate the automated deployment testing and continuous delivery pipelines that are some of the hallmarks of modern cloud-native application development.

this pattern is an extension of the contract-first development pattern in which developers concentrate on building the edges or seams of their application first. with the integration points tested continuously via ci servers, teams can work on their own services and still maintain reasonable assurances that everything will work together properly.

api-first frees organizations from the waterfall, deliberately engineered system that follows a pre-planned orchestration pattern and allows products to evolve into organic, self-organizing ecosystems that can grow to handle new and unforeseen demands.

summary

if you’ve built a monolith (or even an ecosystem of monoliths) that interacts in tightly coupled ways, then your ability to adapt to new needs or create new consumers of existing functionality is hindered. on the other hand, if you adopt the mentality that all applications are just backing services, and that they should be designed api-first, then your system is free to grow, adapt to new load and demand, and accommodate new consumers of existing services without having to stop the world to re-architect yet another closed system.

live, eat, and breathe the api-first lifestyle, and your investment will pay off exponentially.