Decoupling APIs with API First [EN]

8 min readMar 8, 2020

Introduction

Service Oriented Architecture (SOA) values and principles have influenced my life.

Just in case you haven’t followed the SOA series I wrote:

For now, it is a series written only in Portuguese, but if any English or Spanish reader is interested, you can write to me in this post.

I intend to keep the other topics that I have written as a priority, but there is a lot that I already wrote on my Medium that I need to translate.

As stated in the first article, when I went into the SOA world, I thought Service Oriented had a JAR, something like AspectJ is for Aspect Orientation. In my mind, it was all Technology and Programming.

All these first impressions you can follow through the articles above.

To deepen the story a little more, I would like to share with you the person who took me out of my ignorance that Java would solve everything, the man, the legend, the myth: Valério Aymoré Martins.

Valério is that right-most gentleman, and it was he who helped me in my first steps with Service Oriented Architecture, at a research institute known as the Brasília Institute of Technology and Innovation, IBTI (Instituto de Brasília de Tecnologia e Inovação).

After making contact with SOA, instill so much in my head that the service layers decoupling was right, that I had difficulties to enter into a different world of SOAP, REST.

Service layers decoupling

The problem with my transition was was neither SOA nor SOAP. I was a Java analyst at the time, however, I was just an SOA Junior analyst.

When I learned about Contract-First and its advantages, it was as if everything for me had to fit this premise. It doesn’t matter to me if I can make a REST API easily with NodeJS or Spring Boot, if it couldn't be done with Contract-First for me was in a wrong way.

I was very Junior to realize that I was losing a lot of things and developments in this REST, given my immaturity.

The start of this story, you can read here with my story about RAML, and here, when I started my journey with Swagger.

I am not going to go into much of the merit of whether I agree that REST should or should not always follow an API First approach, but I would like to share with you a scenario in which we have seen that API First fits in very well, Customer Journey.

Customer Journey

I worked at IBTI, and later at Core Consulting, in both companies with SOA, and I need to mention another person who influenced me a lot mainly in soft skills issues, André Toffanello. Thanks to Valério’s more technical bias with Toffanello’s out-of-the-box view, I was able to start my mindset with what SOA defines as alignment between business and IT!

This helped me later at AIS Digital with people like Isaac Canan and Rafael Lucyk. With an SOA mindset, I could propose ideas to generate innovation, seeking autonomy, and being able to discuss points of view.

About AIS, I still intend to write another post someday. Let’s go back to SOA and the customer journey.

Contract-First and API First are things that I had a great appreciation for! Given that I always worked as a back-end, I saw this as a significant advantage in decoupling, and the possibility of being able to develop things like mock following the proposed contract, with that, the weight on the back-end team has eased.

However, working in a technology company specialized in digital products helps me to understand an unexpected thing.

It was possible to approach the functional context and granularity of my services, as well as their governance if I approached a team that I would never think that one day I would approach: the UI, UX, and Design team.

API First, UI, UX, and Design, how have I never seen this?

If you want to talk to someone who has an appreciation for services in a Service Oriented Architecture, here are some words that can earn you points with him: granularity, governance, autonomy, composition, among others.

One of the most significant difficulties for professionals in this area is the grain size that a service must have to be considered as agnostic as possible, bringing more Return on Investment (ROI).

When we talk about agnostic services, we are talking about services that we can use in various contexts in service compositions. Therefore, they are not focused on a specific scenario.

I worked on a project at AIS in which the UI, UX, and Design team helped me to realize that they have a vital role with the customer help me with my APIs grain.

Following the two drawings, it is possible to notice the layers that are more or less agnostic, as well as the layers that are closer to the customer’s processes and journey.

At AIS we started doing something very interesting, putting people with the ability to specify APIs together with people who are designing current and new customer journeys.

UI, UX, and Design: Top-Down or Bottom-Up

And how do Top-Down or Bottom-Up influence this?

When we are talking about solutions with legacy applications, the professional who specifies APIs may raise difficulties with the UI, UX, and Design team. The design of some screen prototypes, showing that it may not be possible to achieve the maximum usability and user experience given existing legacy, thus targeting a Bottom-Up approach.

In greenfield scenarios, we can target innovations and abstractions that guide the journey.

In both Top-Down and Bottom-Up scenarios, what do we as API specifiers in an API First approach want? That when the front-end developer or back-end brings the prototyping definitions to life, we will not have surprises like: “oh, this screen will not be able to be implemented like this, because our back-end does not offer this functionality”.

Okay, but what about the code?

I don’t know if Linus Torvalds said that famous phrase, I remember that famous phrase:

Anyway, I know that you developer who is accompanying me must be thinking that I’m messing with you, after all, I had said before I would talk in this post about implementing the project that is already in my GitHub.

I believe that it is important to align these business issues before. Some projects show me that the more we as developers distance ourselves from the business, the less we value ourselves, and the fewer people see the impact of our actions on products and journeys.

Though let’s start discussing some more technical points to give a direction on what we will talk about in the next post, this more technical one, this time, I promise.

Which database should I use in API First?

Thank you very much Igor Vieira for this epic gif!!! hahahahahahahahahahahah

One of the mistakes that we see most when it comes to the customer’s journey is that we, as developers, have already started defining SQL or NOSQL definitions at this point, how to connect with column X, Y, Z, and other things that go together.

The point is that, if we already start looking at and directing our APIs in a strategy in API First with our database, we will naturally be disrupting the customer’s journey. We will be limiting the customer to an experience of something accomplished somehow, five, six, ten years, or more. It is hard to believe that our legacy system is aligned with the customer’s journey we are discovering now.

In a digital approach, we believe that the customer is at the center!

We will talk more about this in the next post. There is a famous phrase that expresses it: “You can’t always win”, to get the contract decoupled with the back-end, we will end up needing to decouple the API model layers with the persistence model layers.

Another interesting point is that sometimes we will have to decrease the customer experience to the detriment of our legacies. However, this should not be the starting point, that is the idea.

In APIX 2019 Kleber Bacili, CEO of Sensedia, an AIS partner and Brazilian representative at Gartner and Forrester Wave in the API Manager category, said an interesting thing:

Although Sensedia has a connector and it integrates directly with a database, this ends up bringing a coupling that we may not want to link directly with our API layer.

And how about APIX 2020? For those who don’t know, registrations for this year are already open.

You can watch APIX 2019 in Sensedia Youtube channel in the English playlist and the Portuguese playlist. There are also some Spanish videos.

AIS Digital was also there! You can check out the guidelines that directed this post, Samuel Corado, and I talked about Transforming your channel strategy with APIs:

In the next post, we will talk about OpenAPI 3.0, Spring Boot, Maven, Gradle and Kotlin. See you later…