Color Mode


    Language

API First

October 7, 2020

We've been building APIs for a long time, enabling our mobile software solutions to communicate with each other across their respective platforms. For years these APIs have been built as part of a "mobile first"-approach, under the guiding light of an internally defined, living document, our so called "API Manifesto", highlighting everything from how URIs are formed to response body formatting and response codes. A recent change in how we document APIs internally, from simple markdown descriptions of individual endpoints to fully fletched OpenAPI specifications and the ability to spawn mock-servers on the fly, has sparked thoughts on how APIs are treated overall in the context of project development within the organization.

Over the past 10 years, being involved with developing and maintaining APIs, I've seen a great deal of approaches to this discipline, some better than others. Some of the worst examples that comes to mind, emerges from different mindsets on how software development should be executed eg. "We need to ship this fast!" (sloppiness), "We need more developers on this to speed up the process" (messy, inconsistent) and "We don't have a mobile developer available at the moment, can we fix this in the API instead?" (platform inconsistency). With no common understanding of "how and why" and "dos and don'ts", the outcome is often disastrous. Yes, in the end it might do the job, but it is in no way a pretty sight, and maintaining these remnants can be a tedious affair.

The Contract

Seen from the perspective of the vendor of services, executing like the examples given above can lead to an immense amount of frustration. Nothing can make a developer tick off more than when presented to source code that doesn't follow expected agreements or when being expected to build it in an unexpected way. The consumers of APIs also have different opinions to what can be expected in responses from API-services.

With an API-First approach, the involved parties make a mutual agreement on the structure and behavior of the service. This agreement is the ultimate reference, "the law", when doubt arise. It can be utilised to easen decision making regarding future development of the service, referring to original structure, as well as a tool to resolve disputes regarding data structure, response codes and HTTP methods.

The Product

Many sources on API First underlines treating the API as a "first class citizen" when building software projects, and this is a term I really like. Basically it means that the API is, if not solely then a part of, the main product that is being developed. This means that it is being managed like other primary aspects of a project. Mark O'Neill, VP of Innovation at AXWAY explains it really well:

The Future

I can imagine a lot of the projects, large and small, I've been working on over the years would have benefited from an API development phase under strict management. Even though you can argue that many smaller productions doesn't really require a fully managed development of an API, many of the elements involved in thinking "API first" are to me quite intriguing, enabling better maintainability and transparency across the different teams involved. With a common contribution from people with multiple perspectives (vendor and consumer) on how the API behaves, it is my belief better results we be created.

I do not expect a paradigm shift like this in the company to happen over night, but this article could potentially become the starting point of such a shift. A lot of well written articles about API first already exists and can be found by a simple google search, so these are my 5 cents on how my life could become a little better by adopting these ideas.

Further reading and references

  • Understanding the API-First Approach to Building Products
  • What is an API First definition?

Header photo by CDC on Unsplash

apidevelopmentapi-firstengineering

Author

Rasmus Ebbesen

Rasmus Ebbesen

Senior Backend Developer

Seasoned backend developer from Copenhagen.

You may also like

March 1, 2023

How to set up Firebase dSYM upload for an iOS project with multiple environments (Xcode 14)

If you ever used Firebase Crashlytics for an iOS app's crash reports, chances are you also encountered the “missing dSYM files” warning in the Firebase console. The crash reports are basically useless without these files. The Firebase Crashlytics document...

Jiri Bucek

Jiri Bucek

iOS

February 14, 2023

How to create a simple app with Flutter on the Web

Recently, Monstarlab has been receiving an increasing number of app development projects using Flutter. In this article, we will have a look at how you can easily create a simple web app using Flutter on the web. How to create a simple sample app For this...

Seiya Shimizu

Seiya Shimizu

FlutterFrontend

ServicesCasesAbout Us
CareersThought LeadershipContact
© 2022 Monstarlab
Information Security PolicyPrivacy PolicyTerms of Service