OpenAPI – Making a Long Story Short

A new startup must always look for ways to build their products better, faster and cheaper. And as part of the journey of establishing a new R&D organization, the outsourcing trend is an important element one must consider.

A short disclaimer: When I joined anecdotes, I was deeply concerned with the idea of outsourcing the front end development process to an offshore team due to past negative experiences I had personally been involved in. I have often tried to encourage management to avoid such actions, BUT, bear with me as I show you how I have been proven wrong, it will be interesting.

To Battle!

Kicking off front end development with an offshore team is no less than a challenging mission, especially when starting from scratch.

On one hand, you want to pass on your heritage, your experience and your “know-how”. And on the other hand, you want your team, no matter where they’re based, to run as fast as they can and lead the way, as you have to focus on the product core (startup mode: ON).

Running as fast as we could towards our MVP, we knew that the front end path had to start alongside the product core development. We found ourselves brainstorming a lot before launching the process, and it created many concerns that drove us–especially me, due to some of the bad memories I had–to come up with ways to keep this process as smooth and seamless as possible.

‍

Think about the following three concerns:

1. How do you coordinate API endpoints? Schemas? Authorization methods?

2. Things change rapidly, especially in a startup; how do you streamline changes? New properties? An updated documentation?

3. How can one start implementing a screen while the product description is not yet clear or complete?

Let me share with you how we coped with these concerns

I will shed some light on how the “schema-first” approach and OpenAPI (aka Swagger) were, and still are, key factors to our success, and how it helped us to nail it with our offshore team.

The popularity of “API description formats” like OpenAPI, RAML and API Blueprint has risen dramatically over the past few years and we have given some serious thought to the best approach for building our API(s). 

API description formats act like a contract that clients can utilize to understand how to best work with your server’s API. They are language-agnostic and easily readable by both humans and machines, helping to easily streamline changes and documentation, and improve the ease of use and implementation for the client.

Schema-first API design promotes the approach of writing your API definition first, in one of the many API Specification languages, before writing any piece of code, thus, producing the “contract” mentioned above.

How did we do it?

OpenAPI was our API description format of choice.

‍

As of writing this article, it is the most popular description format for RESTful APIs, and it has a huge open-source community contributing to it (and to the Swagger toolkit implementing it), with an enormous amount of different tools to ease the development and accessibility processes.

An OpenAPI file allows you to describe your entire API. It can be written in either YAML or JSON formats and together, in combination with the Swagger toolkit, it presents 3 main advantages, which, in my opinion, are the key factors to our success with our offshore team:

1. Helps design APIs with a powerful editor which visually renders your OpenAPI specification and provides real-time error feedback and smart suggestions, to help you build better, more robust and easily editable API specifications that can be streamlined easily.

‍

2. Enables the consumption of your API easily, by both generating server stubs and client SDKs effortlessly. This allows us to easily implement our API specification using libraries which map OpenAPI endpoints to code (connexion in our case – but that’s for another blog post ;)) and the offshore team to easily generate mock APIs and language-specific SDKs. This ultimately enables an easy and seamless way of streamlining changes to schemas and models.

3. Allows “on-the-fly” documentation generation from your OpenAPI definition for visual interaction and easier consumption. Asynchronous development processes now become more convenient and it is easier to share and streamline your API changes quickly and efficiently.

‍

“By doing so, teams don’t even necessarily have to communicate – their systems will work with one another as long as they adhere to the contract. By the time you’re done, everything will work the way it is supposed to, without the need to have massive scrums or pause development while waiting for modules or parts of the codebase to be finished.”

Using A Schema-First Design As Your Single Source of Truth, by Kristopher Sandoval

So these are my thoughts on how to work with an offshore team, and why OpenAPI is a key technology factor in our path to success. Try new things, implement new methodologies and learn fast – it works amazingly well and I’m happy I was proven wrong. 

If you have any thoughts, please feel free to reach out – we are more than happy to help our fellow comrades!

‍