How to Automatically Consume APIs with React

OK, so we just have five minutes, so I'm going to drive it like I stole it. My name is Teodor, I'm a software engineer based in Athens, Greece, I'm working for Proxima Analytics, which is an ethical open source analytics platform. And today I'm going to make just another talk about APIs. And I can tell you that during my career I have developed so many APIs. And I can really tell you that developing APIs is pretty damn hard. You have to think about code changes, documentation, breaking stuff, type safety, like consuming them from different clients or different applications and so on. And there are tools out there, like GraphQL Cogent, ERPC, you name it, that they can kind of semi-automatically generate SDKs in order to consume them into your applications. But that can be a bit tricky and it can be really coupled with the framework we are actually using.

So today we're going to try something simple, just under five minutes, we're going to try and build a simple pizza menu application. We're going to use React and Fastify, React obviously, and Fastify as a server. And as always, type safety is a must. So let's get this one started quickly.

We have a really basic setup about our server, we have a type that identifies what is actually a pizza, like with an ID and a name, and then we can expose two endpoints, one for listing all the pizzas in the menu, and another one just creating a new pizza item in the menu. And in order to document our API and start generating our SDKs, we are going to use two tools.

The first one is called Swagger, which is a way of documenting RESTful APIs, and on top of that we're going to use the OpenAPI, which is actually a specification to do so. They work with different frameworks, different languages, they have too many clients that you can consume as well. And in order to do so, we are going to install two packages for our Fastify server, the first one is the Fastify Swagger module, and the other one is the UI that we want to bring up.

In order to bootstrap these two modules, the setup is pretty basic, so first we need to include the modules in our server, add some specification about the APIs, like a description, and then on the very last line we're going to take the output from the Swagger module and write it into our file system. So let's start describing our APIs.

First up, we have an ID, which is unique throughout our code base, and then we're going to use tags. We can use tags in order to separate different resources, APIs, and so on. And in order to describe our API, we have to actually describe just the response, because we have no parameters or query parameters, and so on. So our response is an object, and we are returning back an array of two of pizza menu items, which have an ID and a name as well. And last but not least, we have to actually include the schema into our route in our Fastify server.

In a similar manner, we're going to do the same for the creation endpoint, but this time we have to provide actually one parameter, which is the name of the pizza item. In a similar fashion, the response gets back that ID to the client. In the same manner as well, we're going to attach the schema into our route.

Once we have everything ready, this is the Fastify React UI, where you can have the full documentation about every single endpoint. You actually have smart defaults there. You can test the API in the browser, and so on. But you might be asking where React comes into that equation, right?

In order to generate our SDK, we are going to use Orval. Orval is an open source tool that takes up the OpenAVI specification and generates the SDK client. It works with different frameworks like Svelte, Vue, with different fetching libraries like SWR, and React Query as well. We have to install, globally or inside our project, the Orval SDK, and then we're going to run the Orval CLI using the OpenAVI specification as an input, and then targeting where we want our client to get generated.

In order to list... This is a pretty simple component that actually lists everything, lists all the pizza menu items. As you can see, the very first line is actually what got generated by Orval. And in a similar manner, we can create a really simple form.

We have a mutation there. So Orval generates the mutation, and we can consume it inside our components as well. And you might be asking about testing. Orval takes that into the equation as well.

So out of the box, we have mock service worker-generated mocks. So it's pretty fairly easy to test everything as we need so. And there's more that you can actually do, because everything's like uniform. You can use Zod, for example, in order to provide uniform validation in your back-end and the front-end as well.

You don't have to stuck with Fastify, so you can use Rails or Next.js or Express, you name it. So there are like implementations in the ecosystem for so many languages and frameworks. You can actually consume APIs from different resources, even open publicly available APIs. Since everything gets committed, the SDK gets committed to our source control system, everything is in place so we can track down changes and so on. And last but not least, you can actually take that open API specification and generate your own documents and so on using the Swagger UI and Redux doc asserts and so on. The code is publicly available in my GitHub profile, so feel free to jump into, take a look how it works, maybe give me some comments and so on.