TLDR; This post is about Swagger and how it improves the communication from the two sides of the coin via a contract. Thoughts? Jump in the story 🤓.

During my career as a Software Engineer I've spent the most of the time in the FE layer. In this side of the world you are in most of the cases a consumer of APIs, where your intention is mainly to display the data in a good way to the end user. In the other side the intention is mainly to keep good communication among services and performance.

I will share with you some stories about use cases I have had along my career as a Software Engineer.

All in the FE side:

4 years ago there was a case where I needed to display some data coming from an API, this API was already defined, additional changes couldn't be made. The desired displaying of the data was different compared to the data provided. However, for this case my job was "easy" because as the API was already defined I could manage to get the data and map it in the way I needed to be displayed. Voila!

Miscommunication and lack of documentation

3 years ago my team was defining a new API to display some data, I (FE) got some requirements to display the data; and the BE got some requirements to manipulate the data, we jumped on a call and briefly defined the Data Structure for the response and request, everything was fine by then. Suddenly there comes the inevitable: requirement change. The requirement change was in the BE layer (wasn't communicated nor re-evaluated), so I proceeded and finished the FE as agreed on the first call. The issue was that we didn't have a documentation guide to describe the API definition and we ended up with a puzzle that couldn't be easily solved.

At the end we managed to glue the API to the desired behavior but this could have been prevented with a good workflow. ;)

Database document describing the data shape

2+ years ago I gave it a try to use Firebase DB, what's the advantage? You don't need to define APIs, you consume APIs based on your Document Objects, you need a user object? You just create it, you need a pet object you just create it. For this case it was easy because the data was created from the FE on demand and consumed on demand. Cheers mate!

Jumping to the other side

1+ year ago I started working as a Full Stack Engineer, having to create my own APIs to be consumed by me and other members in the team, good thing is now I can change and manipulate the API in the way that I need it from the FE layer as well as in the BE layer, however there was still a gap, a piece in the story that made the APIs complex, there were some APIs in the existing code base and they lacked of documentation, that's when I remembered that 3 years ago I had a similar problem and someone mentioned Swagger.

There it comes the happy ending on this story...

Nowadays

Now when someone is going to create an API we first start defining it, how? We define the contract in a Swagger way. But what is that!?. "Swagger makes API design a breeze, with easy-to-use tools for developers, architects, and product owners". Basically a good tool to design, test and maintain your APIs.
There's an old saying that the time that you spend analyzing is the time you will save when you are developing time 3 or more.

I wouldn't jump into details but here you can find an example of an API definition using this tool: https://petstore.swagger.io/

The following is a list of the advantages:

• Describe the representation of your payload from the request and response
• Show the available methods for your API
• Include any additional parameters in the headers
• Version your APIs and show the differences on those
• Mock some data and test they actually work
• Have a contract from both sides: FE and BE

What's your story? Which best practices do you follow?

Thanks for reading!