Three cheers for OpenAPI 3 - Jowanza Joseph

Transcript generated with OpenAI Whisper large-v2.

I am excited to talk about OpenAPI 3 today. As someone who is working on a new company building APIs, this has been an important specification and made my job a lot easier. I wanted to just give a little intro and talk through how exactly it makes my life easier. For the agenda, I'll talk about why OpenAPI 3 a bit. I'll talk about my experience building API integrations across different fintech domains. I'll talk about OpenAPI 3 specification, its history, its use cases. I will do a demo of some OpenAPI 3 tools, and then I'll wrap up at that point. Let's talk for a second about financial APIs. Some of the most popular financial APIs out there, like the Stripe API, which enables you to make payments online. This API has enabled all sorts of new use cases for payments in the world and in apps. There are also open banking, so Plaid, Fnicity, these APIs allow you to connect to bank accounts and programmatically exchange information. But all of these together can really enrich our lives as individuals and also our lives as businesses by enabling that quick transport of data, and then enabling new ways to look at things like underwriting. Understanding someone's financial history, some alternatives to our traditional methods of underwriting, for example, and then other financial instruments as well. That's what I am building, and that's why I'm interfacing with so many different types of APIs. I've encountered quite a bit of difficulties with that, and OpenAPI 3, whenever I have a specification for that, has made things a lot easier. Let's talk a little bit about RESTful APIs for a second. In general, this is your basic setup for a CRUD API. You will have five methods, so a get, a post, a put, a patch, and a delete. Get should give you a list of that object back. In this case, if you have slash products on the path without the SKU on the end, that should give you back all the products in that collection. If you add the SKU to the end, then that should give you the one product. Post will allow you to create products. You should have some body that corresponds to a product, and you'll be able to create that. Put would give you a complete update, so you are replacing that SKU with a new SKU, but keeping the same ID. Patch would allow you to update one field, so a mutation of that data, and then delete would allow you to delete that data. This is the philosophical idea behind the HTTP and REST APIs. However, the reality is that people don't all implement this the same way. Some ways that this can go wrong and that API design can be hard are small things to big things. Let's talk about some of the small things. Let's consider someone who believes that instead of making this plural products, that it should be product. That's one way that they can do it. There also may be some APIs that believe that this is too robust and too many methods, and so they might make a post API for everything. There might be post slash products slash delete, and then that would take over the same effect as a delete HTTP method. Or you may have the patches and the puts and the gets all be implemented in post as well. Furthermore, you may not want to use the path in order to pass this QID. You may pass it in a header, you may pass it in a body. As someone who's integrating with an API, you get used to the pattern that you see, and then you go to another API and they follow a completely different pattern. Reusing your code, doing things in a way that is modular, becomes very difficult and strenuous. OpenAPI 3 is an attempt to, one, standardize on how these APIs should look, and then two, provide some ecosystem around these APIs, so consuming them is a little bit easier. OpenAPI 3, what it is, is a protocol or more specifically, a machine-readable language agnostic and open protocol for REST APIs. It's a way to describe RESTful web APIs in a machine-readable and language agnostic format. What do you get in return for that is community. Once things are machine-readable and language agnostic, many tools will pop up. You get an ecosystem, so you get a wider array of tools, you get them being interoperable, which is the last point. As far as the lineage or the composition of OpenAPI 3, what it is, is essentially JSON schema to describe the JSON objects that are being passed around over HTTP, and then some other, you can call it syntactic sugar to explain the rest of things that could happen in a web API. You might wonder how this relates to Swagger. Swagger actually is, you can think of it the grandfather of OpenAPI 3. Essentially, Swagger was the initial attempt to do this, and then it spun out into something that was more generalizable, which is what OpenAPI 3 is. Swagger and OpenAPI 3 are mostly compatible with each other. You find places where they aren't, and it's a little bit frustrating. Let's jump into a demo of some of the OpenAPI 3 tools. What I have here is Repolit. Some of you probably have worked with this, but essentially, I'm just going to go through six different tasks with different OpenAPI 3 tools. First, I'm going to start by taking an OpenAPI 3 specification, and then consuming it and converting all the endpoints into TypeScript interfaces. Then I'm going to talk a little bit about how you can create your own specification, what that looks like. Then I'm going to take an existing OpenAPI 3 specification and generate a mock server out of it. Based on the spec, I simply will run a mock server and then be able to run some commands against that over Postman. Then I will talk about how you can take an OpenAPI 3 spec and then turn it into a nice documentation that you can share with either your customers or friends, or colleagues. Then talk about generating a Postman collection out of an OpenAPI 3 spec. And finally, end with generating an SDK. This is specifically a TypeScript SDK. TypeScript is just what we've been using for the company. It's the thing I'm the most familiar with at the moment. Before I do any of that, let's just take a quick gander at one of these specifications. This one is one that I borrowed from this lady named Lorna. She's trying to make this API that allows you to retrieve planets in the solar system. In this API, you can see she's got an OpenAPI 3 specification version. She's got some description. Then here are the paths. There's a get for planets, so slash planets. Then there's a get with slash planets slash ID. Pretty straightforward. It describes what you can expect from the API. One nice thing here is that it also gives these examples of what the values can be. That comes in handy when you're trying to generate a mock server. Without further ado, we're going to start by consuming this OpenAPI spec, actually a different one from the planets one. This one's wordy. This is a CRM, a Customer Resource Management API. It's pretty long, but effectively, we're just going to take this, which is like multiple method API, and then just turn it into some schemas that we can use in TypeScript. We'll do that with this tool called OpenAPI TypeScript, which just takes any valid spec of OpenAPI, and then turns it into TypeScript schema. Let's copy this. We'll just run that. It might ask me to install this. Okay, that's fine. One second. I think I have a typo there. Sorry. That created the schema.ts file here. For each of the endpoints, I've generated these different interfaces in TypeScript. I've got the slash CRM slash leads endpoint, and that's a get operation, and there's also a post operation for that. Then I've got these different webhooks. I've got the interfaces that are specific to the regex that they're described with. For example, this needs to be ISO format for time, and then I've got all that that just read directly from that OpenAPI spec. That just continues forever. It's a pretty long API, so I won't make that too long. Pretty simple. This would work in any language. There's tooling for this all because you have the specification that describes this API. We'll skip through this. We already talked about this API. We'll move on to mocking. We're going to mock that planets API that I just showed. Let me install that too. What this is going to do is it's going to spin up a web server on port 8080, and then in Repolit, basically, we'll forward port 8080 to this domain here. From that, I can make a get request against this. I'll come over here to the postman and then make a get against planets. Then you'll see here that I get a planet Saturn back. Then also, there's another API endpoint where I could do an ID, and so I'll also get planet back for that. Simply, I didn't write any code, and then I've got an API that just works against that specification, which could come in handy if you're working with APIs like I am all day. All right, so let's do the next one. So, okay. So, next, we're going to spin up some documentation. So, I'm going to use this tool called Redocly, which takes an open API specification, all the examples, and then provides a nice page for you to display your REST API. So, let's do that. Okay, so. Okay, so basically, this whole API is described in that doc, and then what you get is this page here. So, it has all the notes, explains the headers in your API, API keys, and then if you come down to the bottom here where the actual API is, so it'll give you any kind of authorization parameters. It'll give you some examples of code, so you can do Python or Java, and it will automatically generate how this code should look. It gives you all your responses, and it's pretty solid for just auto-generating it, and as you get used to using Redocly, you can generate nicer and nicer pages, and Redocly isn't the only tool that works with these open API 3 specs. There's several, but this is kind of one of the nicest and sort of easiest to use ones, so it's one that I recommend. All right, so let's keep moving here. So, the next one, we're gonna generate a Postman collection, so let's see. Let's actually just close this web view. I won't need that anymore. Move this over here, and okay, so we're gonna take that same example spec that has a CRM API and make a Postman collection, so then we'll import that into Postman afterward. Okay, so that was saved in this temp directory, so we got temp converted, CRM API.json, so we'll download that, and then open up Postman, import new collection, and sweet. So, now we've got that full API in Postman, and then you can add any of these default values as well and add a Postman environment if needed, so that's an easy way to get started if you were trying to consume a new API. Okay, and finally, we're going to generate this SDK, so we're gonna take that same example spec and then generate an SDK for TypeScript from it. Okay, so now we've got this SDK.ts, so this is effectively an SDK that you can import and start using that implements this entire API, so it's got all the types, all of the methods, and exactly to the specification that was written. So, let's go back here. Okay, so these are all the benefits that you can get from OpenAPI 3, so testing, being able to mock, being able to use the integrations in the ecosystem, and I think the most important, the sanity, so having a way to describe an API and letting kind of all the heterogeneity happen from however creative people want to be in defining their APIs, but still having a way to describe it has made my life a lot easier. Being able to import the Stripe API as a spec or the Plaid API just makes my life 100 times easier, and so I really, really love this tool, and if you haven't used it, I hope that you get a chance to, and that's it for me.