Conf42 JavaScript 2022 - Online

The changing API problem

Video size:

Abstract

After a bad experience with some backend teams that changed the API without informing the frontend team in any way, we decided to introduce the API First paradigm in our development, adopting the OpenAPI specifications. This, together with a contract-based development, would allow us to detect such changes earlier and not reach critical moments at the end of the sprint.

One of the problems we encountered was than all the tools we found depend on java that allow, so we made the decision to build our own CLI in nodejs. From this need, several applications are born, aimed at different moments of development. Following the specifications contained in an OpenAPI file, allows us to:

automatically create code in javascript or typescript, both for client and server, so that we save a lot of time that we can spend thinking. This functionality is already available within the application openapi-nodejs-cli automatically create a mock server, which allows the front team not to have to wait for the API to be finished check that an API meets the indicated OpenAPI specifications, which allows us to test within the development flow for early detection of changes in the API

Summary

  • Julio Regis is head frontend developer at Singular. He talks about communication between front end and back end teams. Using open API specifications files, development teams can work in parallel. Two tools are currently in production and another is being developed.

Transcript

This transcript was autogenerated. To make changes, submit a PR.
Jamaica real time feedback into the behavior of your distributed systems and observing changes exceptions errors in real time allows you to not only experiment with confidence, but respond instantly to get things working again. Code hello everybody, I'm here to talk about one of the problems we have in project development with front end and back end teams. The problem is not usually a technology problem, it's a communication problem. I introduce myself, my name is Julio Regis. I'm head frontend developer at Singular. I have more than 19 years of experience in web development and currently I'm leading the frontend side of OSS initiative at Sngular. Let's talk about the pain. The main problem when we start a project with front end and side and back end teams is when front end team can start to work. Currently we made use of mocks to start development the front side, but it makes the communication can be different. When we are in the integration moment, API needs time to make his work and we can or mock the expected input and outputs from API or wait them to finish their work. This can block the entire frontend team a lot of time and we are waiting for the server side can be a lot of time waiting. Another pain is that when we integrate the two systems, the difference between them or even a difference made in API in the future. Any changed can broke the front end site. If we don't find it early, what's the solution? The solution is talk talk between both teams. Both teams can negotiate the API signature until they reach an agreement. When both agree with the contract, we can start development coding each one each side. In this moment, development teams can work in parallel without any block between them. The developers are happy because the API is well designed, they agree with the specification and the API is well documented. Also reduce the risk of failure because all teams must honor the contract. If one team made a change without telling it to the other team, it will broke before integration time. We can introduce it in OCI CD pipes. Also, how can we communicate and agree the communication between both sides using open API specifications files? Here we can define endpoints, methods, parameters, inputs, outputs, anything. Anybody made this before? Yes there are more tools in Internet that you can download and use for this, but they usually are over Java virtual machine we don't want to have frontend developers to install all the Java world, so we want to make it in Nodejs, Novg, JS. They have all installed in their development computers, so it's easy to start to use these tools. Which are these tools? Well, we have two tools currently, one in production state and another we are developing nowadays. The first one allow us to create the scaffolding magically. We have no need to code anything to have a functional version of the API calls. We simply read and open API specification files and it made us server, client or interface. So we speak the same language between all the teams. As I said before, this is already in production and can be startled from global NPM registry. So you all can test it and send us any comment you want. Open us any issues if you find any bug and we'll try to fix them as soon as possible with the team we have in sngular. The other tool will have two different nodejs. The first one in which we are working in this moment is the possibility of launch a mock server without any human interaction. We can read and open up a specification file and in this moment we have working endpoints so we can start to connect them from our front end application. The second part of this project will allow us to validate any API server to check if works with the specification we agreed before. Let's try them. Well, first tool is the code generator. We have a simple yaml file with anything, some endpoints and some methods and the response of them. When we launch the tools we generate code to server and client inside without doing anything. We can see in this execution we create client and server code and interface code to communicate the object to define the object we are going to use. Let's see what it was create automatically. We have a client code with the endpoints of the specifications file and the methods we are defined in the specification. In server side we have an express server with the endpoints and methods. In the scaffolding we only launch trigger an error so you can know it's not implemented. But here you can introduce your own code with database connections or any service you need and it makes the interface we are going to use. In this sample we have a group interface and a schema interface and can user interface in the other tool which is in development stage. In this moment we are going to launch a moss server and with Postman we are going to see the inputs and output we can retrieve from the server. Simply we launch the server, detect the roads in the file and in memory we launch the server as we can see was 2 seconds or so. Launching this server, let's go to Postman, let's retrieve the schema registry. List is one sample we have and when we call our mock server it returns a list as we can see in the output a list now one object only but we have data in this moment we see also we can make another request which is going to retrieve was an only object and we can make also post and put request with validation. The specification files of post and put define the input. We are expecting to receive and validate the input data with the specification. So if we remove a field, mandatory field, we can see it's going to give us an error giving us which key is missing from the input. If we add a key which is not defined in the spec file, it will give us another error indicating the field is not allows to use in this request. The put request has the same validation than the post request. We can remove any field, any mandatory field, and we have the same error. And that's all. If you want contact to me in Twitter. You can tell me anything about these tools, any question, any issue you have using them on your day by day development. You can contact me via email also and you can download the code so you can see what we did at GitHub. Thank you for your attendance and I'll be here for anything you want.
...

Julio Cesar Abalde Reyes

Head at Corunet @ Sngular

Julio Cesar Abalde Reyes's LinkedIn account Julio Cesar Abalde Reyes's twitter account



Awesome tech events for

Priority access to all content

Video hallway track

Community chat

Exclusive promotions and giveaways