What is OpenAPI?

[00:00:00]
>> Steve Kinney: Having Zod is really great for confirming the stuff that comes in through the gates is valid, but it's a JavaScript instead of JavaScript functions, right? And so that has the problem of being JavaScript, right? Which I like JavaScript, I think is great. However, JavaScript objects don't work super well in go because they're different languages.

[00:00:25]
So obviously this is a very common problem, especially over the years, because it turns out there's a lot of back end languages. There's one in the browser, and sometimes back ends are in different languages. So an open API spec is effectively more of a convention than any kind of piece of technology, right?

[00:00:44]
There's nothing like there's no tech technically, in an open API spec. It is simply a convention to follow and you might see them in yaml, you might see them in JSON. They are the same thing, effectively, where you know it is to some version of this specs. This is the Yaml1 in the repo.

[00:01:02]
Actually in all three folders, there is a openai.json, which is for our test schema API. That one, it's written in JSON as well. I did both so you could see them. We'll look at the YAML one right now, because it's just a little bit easier to read. That's kind of the selling point of yaml.

[00:01:18]
Which is you've got some metadata, and then you've got for instance, all of the paths that an API should support, right? So here, in this case, we've got /users that has a get method, a little bit of information about what that thing is supposed to do, a little bit of documentation, if you will, the parameters that it takes.

[00:01:38]
And the point that is going to be somewhat useful for our purposes is whether you know it or not that is JSON schema, right? This is the YAML file you can go see in JSON. JSON schema, again, just a convention, just an agreed upon structure for defining the parameters of either the arguments or the return value of.

[00:02:02]
In this case, an API, but could literally just be functions, right, in a language-agnostic format that everyone just agrees to. There's, again, no technology behind this other than committees. And so here we've got the path both the get okay, it takes this search query and then for what do you want to search for?

[00:02:26]
And then a page number, right? What are the responses that it might give you? Well, if it's a 200 you're probably getting back an array of users, right? And then we'll talk about what is a user, we'll get there. Again, you have the same thing for the post.

[00:02:43]
What is required in the body and what is optional in the body? This should be all mapping to TypeScript stuff in your head, right? Cuz, again, that's why it's a standard, it will map to something in most languages and there are nuances, right, for languages that have both ints and floats.

[00:03:00]
That will be meaningful in those languages. In JavaScript, they'll just both be a number, right? There are little nuances but you can basically talk about what are the parameters in a path? What are the request body? What are the responses, the status codes that you could get effectively a contract Test for describing how an API is supposed to work.

[00:03:23]
And this is useful because then on the server, you can then say, okay, we're agreeing to this contract. Great, I can expect the request bodies to come in to match these things, right? And the front end team is like, yeah, yeah, you can right and then the front end team is like.

[00:03:39]
But when I make that API request, like a get request or the response I get back, you're going to hold up your end of the contract, right? Now obviously you schema validate, whether that's JSON schema or Zod schemas or whatever. You schema validate and again trust, but verify is the name of the game here.

[00:03:59]
But it is a standard document for creating some kinda contract so that both sides, even if they are in completely different languages. And can't share the types in a mono repo or an NPM package, right, can theoretically do it. So at temporal, we have got a open API doc for HTTP API.

[00:04:20]
It is generated directly from the go proto buffs, right, which is a different standard that I've got some slides on if we want, but like, it's just a different way of doing this. And they automatically generate that document, and because it's generated out of their code, right? I can trust that it mostly works, and I have the advantage of since we are an open source project with a public exposed API.

[00:04:44]
The chance of a breaking change is a lot lower because we agreed not to do that to our customers. So means the back-end team is less likely to do it to me. Bugs happen, right? Issues happen, but generally speaking, it's generated from code, and we have it ready to rock and roll.

[00:05:00]
So first you have that paths plural, and literally, we will do this together and I do this at work is I just generate a client to do all the fetch calls. I don't write a single fetch call myself. I have a client that I just generate from their contract that where everything is perfectly typed, and we will get there you have and then under components, it's like, okay, so this one's only got a user.

[00:05:26]
This is effectively, some of this should look somewhat familiar to what we were doing by hand, right? This is what a user is, right? Id, this is kind of from the examples that we saw earlier. I do generated one, a create user request, so on and so forth, right?

[00:05:43]
A slightly more involved one is in the repo. This one I just did in JSON just to show you both, where it is a description based on the API that we have been working with the entire time of what it should look like. Now, can you generate one of these from code?

[00:06:04]
Yes, if you also had all that structure in your code, right? We started with a wild west API, so it's a little bit trickier and I'll show you some techniques for doing it. But even if you can just Figure out what it ought to be. You can use odd schemas to generate this.

[00:06:22]
You can use JSON schema and then you can make them both work across the way. But this is effectively a representation of everything that my API that we've been working with does. We're going to focus a little bit more on the client side piece, but we'll look at like, because, the reasoning is that, like generating one from the code is a little bit tedious.

[00:06:43]
There are lots of tools that you can use, and you will see why we will not be doing it live in a moment. For instance, if you one annotated their API with JS Doc, you can generate one for free, right? The problem is, we'd be doing a lot of writing, which for real production code base, maybe someone ought to do, right?

[00:07:13]
Cuz internally, you can make sure that your API adheres to your own contract. We'll see how to do that in a second and then also for the other side, for a throwaway app, writing this much by hand for 800 lines is not worth it, right? But again, if the safety is worth it to you, it is there you.