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.