**To receive your the 40% OFF coupon for Manning Publications (good for all our products in all formats) visit us at Facebook - click on "Send A Message"and type "YES"**

Special Guest: Josh Ponelat.

Hey folks, I'm a super busy guy and you probably are too. You probably have a lot going on with kids going back to school, maybe some new projects at work. You've got open source stuff you're doing or a blog or a podcast or who knows what else, right? But you've got stuff going on and if you've got a lot of stuff going on, it's really hard to do the things that you need to do in order to stay healthy. And one of those things, at least for me, is eating healthy. So when I'm in the middle of a project or I just got off a call with a client or something like that, a lot of times I'm running downstairs, seeing what I can find that's easy to make in a minute or two, and then running back upstairs. And so sometimes that turns out to be popcorn or crackers or something little. Or if not that, then something that at least isn't all that healthy for me to eat. Uh, the other issue I have is that I've been eating keto for my diabetes and it really makes a major difference for me as far as my ability to feel good if I'm eating well versus eating stuff that I shouldn't eat. And so I was looking around to try and find something that would work out for me and I found these Factor meals. Now Factor is great because A, they're healthy. They actually had a keto line that I could get for my stuff and that made a major difference for me because all I had to do was pick it up, put it in the microwave for a couple of minutes and it was done. They're fresh and never frozen. They do send it to you in a cold pack. It's awesome. They also have a gourmet plus option that's cooked by chefs and it's got all the good stuff like broccolini, truffle butter, asparagus, so good. And, uh, you know, you can get lunch, you can get dinner. Uh, they have options that are high calorie, low calorie, um, protein plus meals with 30 grams or more of protein. Anyway, they've got all kinds of options. So you can round that out, you can get snacks like apple cinnamon pancakes or butter and cheddar egg bites, potato bacon and egg, breakfast skillet. You know, obviously if I'm eating keto, I don't do all of that stuff. They have smoothies, they have shakes, they have juices. Anyway, they've got all kinds of stuff and it is all healthy and like I said, it's never frozen. So anyway, I ate them, I loved them, tasted great. And like I said, you can get them cooked. It says two minutes on the package. I found that it took it about three minutes for mine to cook, but three minutes is fast and easy and then I can get back to writing code. So if you want to go check out Factor, go check it out at factormeals. Head to factormeals.com slash JSJabber50 and use the code JSJabber50 to get 50% off. That's code JSJabber50 at factormeals.com slash JSJabber50 to get 50% off.

Hey folks, I'm a super busy guy and you probably are too. You probably have a lot going on with kids going back to school, maybe some new projects at work. You've got open source stuff you're doing or a blog or a podcast or who knows what else, right? But you've got stuff going on and if you've got a lot of stuff going on, it's really hard to do the things that you need to do in order to stay healthy. And one of those things, at least for me, is eating healthy. So when I'm in the middle of a project or I just got off a call with a client or something like that. A lot of times I'm running downstairs, seeing what I can find that's easy to make in a minute or two, and then running back upstairs. And so sometimes that turns out to be popcorn or crackers or something little, or if not that, then something that at least isn't all that healthy for me to eat. Uh, the other issue I have is that I've been eating keto for my diabetes and it really makes a major difference for me as far as my ability to feel good if I'm eating well versus eating stuff that I shouldn't eat. And so, um, I was looking around to try and find something that would work out for me and I found these factor meals. Now factor is great because a, they're healthy. They actually had a keto, uh, line that I could get for my stuff. And that made a major difference for me because all I had to do is pick it up, put it in the microwave for a couple of minutes and it was done. Um, they're fresh and never frozen. They do send it to you in a cold pack, it's awesome. They also have a gourmet plus option that's cooked by chefs and it's got all the good stuff like broccolini, truffle butter, asparagus, so good. And you can get lunch, you can get dinner. They have options that are high calorie, low calorie, protein plus meals with 30 grams or more protein. Anyway, they've got all kinds of options. So you can round that out, you can get snacks like apple cinnamon pancakes or butter and cheddar egg bites, potato bacon and egg, breakfast skillet, you know obviously if I'm eating keto I don't do all of that stuff. They have smoothies, they have shakes, they have juices, anyway they've got all kinds of stuff and it is all healthy and like I said it's never frozen. So anyway I ate them, I loved them, tasted great and like I said you can get them cooked. It says two minutes on the package. I found that it took it about three minutes for mine to cook, but three minutes is fast and easy and then I can get back to writing code. So if you want to go check out Factor, go check it out at factormeals, head to factormeals.com slash JSJabber50 and use the code JSJabber50 to get 50% off. That's code JSJabber50 at factormeals.com slash JSJabber50 to get 50% off.

 

CHARLES MAX_WOOD: Hey everybody and welcome to another episode of JavaScript Jabber. This week on our panel we have Dan Shappir. 

DAN_SHAPPIR: Hey, hey, all the way from Tel Aviv. 

CHARLES MAX_WOOD: I'm Charles Max Wood from DevChat.TV. We have a special guest this week and that is Josh Ponilat. 

JOSH_PONELAT: It's Josh Ponilat. Hi, from South Africa. His countries are cool. 

CHARLES MAX_WOOD: That's really cool. I've talked to a few people from South Africa over the years doing the show. Dan's in Israel and I'm in the United States, so we're totally multinational here.

JOSH_PONELAT: So most people know two places in South Africa. It's either Johannesburg or Cape Town. I'm in neither. It's a very small town along the coast. Kind of sleepy, kind of touristy. It's called Plettenberg Bay should check it out. It's really beautiful. 

CHARLES MAX_WOOD: Great. So after this you'll go to the beach, maybe go fishing. 

JOSH_PONELAT: I think a good Mai Tai in a, in a beer or something like that, you know, because why not? Right? Yeah. 

DAN_SHAPPIR: By the way, we're in South Africa. 

JOSH_PONELAT: Live in paradise. 

CHARLES MAX_WOOD: All right. I'm done talking about it. It's not going to get about freezing here today. So, um, 

 

Hey folks, this is Charles Maxwood and I just launched my book, Max Coder's guide to finding your dream developer job. It's up on Amazon. We self-published it. I would love your support. If you want to go check it out, you can find it there. The Max Coders Guide to Finding Your Dream Developer Job. Have a good one. Max out. 

 

CHARLES MAX_WOOD: We brought you on to talk about Swagger and OpenAPI. Do you want to just kind of give us the quick elevator pitch as far as what Swagger is, OpenAPI is, and kind of how they tie together, and then we can dive in a little deeper on the discussion? 

JOSH_PONELAT: Yeah, sure. And that's actually a big question because Swagger and OpenAPI are used so interchangeably that a lot of people struggle with it, and it's silly. It's silly because it was sort of the disambiguation didn't launch easily. So it started as Swagger. Everything was Swagger and Swagger is a specification or a set of protocols around describing restful APIs. That's the buzzword, right? Restful APIs. And then when Swagger got bigger and larger, it got taken over by a company called SmartBear. And when SmartBear took over, they wanted to keep the heart of it as open source and as open as possible. So they donated the specification, the thing that describes it into the open Linux foundation, and that's called open API. So going forward, open API is the spec and swagger is just the tooling that SmartBear kept. Hopefully, that sort of gets us going there and then we can like touch on it again, figure that disambiguation out.

CHARLES MAX_WOOD: Yeah, it's interesting. I kind of went and dug through like the Swagger website and the open API website. And I'm still not sure if I'm completely clear on what they do. Do you want to just talk a little bit about how Swagger and opening API work to solve some of these issues? 

JOSH_PONELAT: Yeah. So if, I mean, this is a, this is front end, right? So we know what package.json is, right? It's this JSON file where we throw in our dependencies and we've got like a field called name. In order to make package.json work, we need to know what fields can go in there. Open API is the specification for these files, and it basically says which fields can go in there. The purpose of this file is to describe an API. If you have, say, Twitter's API and you want to know how to send a tweet, you got to know its method, say post. You got to know its URL, say, I don't know, slash tweets. I probably shouldn't have picked Twitter's API. It's not my go-to. In order to capture those details, you need to have a way of capturing those details. I mean, sure, you could just write it down in napkin, but open API is a standard way of describing those details. It's typically a YAML file. So if I were to give you an open API definition, I'd be giving you a YAML file. And from that, because it's done to spec, you know, you get all the benefits. You can create documentation or you can get tooling to understand an API what's in it and what the data going in and coming out looks like. 

DAN_SHAPPIR: So basically you're saying that it's essentially a standard schema for restful APIs? 

JOSH_PONELAT: That's it. Yeah. So that's open API. That's the big buzzword because open API is the one that's the heart of it. It's the schema. 

CHARLES MAX_WOOD: Dan said restful APIs and I'm wondering, does it encompass any other sorts of API schemas or approaches? You know, GraphQL kind of does it differently enough to where I don't know if this specification makes sense for that. 

JOSH_PONELAT: So no, you know, OpenAPI does not describe other types of APIs and where I'd say type would be something like gRPC, GraphQL, or any other RPC frameworks. The focus is on HTTP. So now we say RESTful, but RESTful is also a design constraint. It's bigger than HTTP specifically. So OpenAPI would be probably be best described as an HTTP schema, describing the HTTP details, like method, URL, parameters, and the body. 

CHARLES MAX_WOOD: That makes sense. I'm also wondering with OpenAPIs, so yes, you provide, make a post request to this URL. Does it also include the authentication schema? 

JOSH_PONELAT: So yeah, it does include those details. In authentication, they typically get carried over either as a header, you know, so you could describe it just as the header itself. But open API does have a special cases. So special ways of describing authentication and authorization, and you can give them a single name and they can go as detailed as being say, Oauth2, HTTP basic, especially in the latest specification. 

CHARLES MAX_WOOD: I gotcha. So yeah, you can say it's a JWT or it's from OAuth or it's an I key and a header or a token from one of these in a header or anything like that, you can put that in there. 

JOSH_PONELAT: So you could describe it just using headers or just using query parameters, which typically the two that I'd be in. But there is a special case because it is so standardized and you want to have the nuances of it just right in one place. Say, this is OAuth 2. I'm not going to say this is just an authorization header. Because you want to know those details and that's important to communicate.

CHARLES MAX_WOOD: Yeah, it's an Auth.Restation header, but you got the token for it from OAuth 2. 

JOSH_PONELAT: Gotcha. Exactly. 

CHARLES MAX_WOOD: All right. So the other thing is, is on the parameters, are they typed or are there recommendations for the specific format? Cause I may say like start date, end date, but here in the U S we do month, day, year, and in other parts of the world is day, month, year. So I may want to specify even the format, right? 

JOSH_PONELAT: So OpenAPI does its best and I'll describe how it does that in a little bit of, you know, high level of view. But it's going to have its limitations of how far it can describe the details of the request response. Because it does describe both, right? They're both important. In your case, it would be something like this is a string and it has a format of date time. It wouldn't go so far. So date time would be against one of the ISO standards. It wouldn't easily be able to describe, say, an American format date string. But you could use something like a regex or something like that to sort of put limits on the string that you're sending? 

DAN_SHAPPIR: So to clarify this point, suppose I'm describing, I'm building an API and I want to use the open API. Does it generally mean that I just apply existing schemas to my API or does it mean that I need to extend the schema to cover my API? What would be the typical way that I would go about it? 

JOSH_PONELAT: Okay. Let me try and break that out there. OpenAPI gives you the spec of how to describe APIs. You would start with either a tool or your IDE, because now you want to write or generate a YAML file that describes your API. You would start with the basics like URL and method. When it comes to describing the pieces of it, say the query parameter or more specifically the body parameter, the body parameter specifically uses something called JSON schema or a derivative. It's sort of a, they kind of fudged it a bit there when it's, it's not full JSON schema, they're changing this now, but it is very, very close to JSON schema. That would be the shape or type of data that you're sending back and forth. Beyond that would be, you could say that this is a JSON or this is an XML body type or anything that fits that sort of standard by adding the MIME type. I mean, we can look into a quick run-through of how you would get something working from OpenAPI. I find a lot of people find that useful. Should we give it a bash? 

DAN_SHAPPIR: Yeah, sounds good to me. 

JOSH_PONELAT: Okay. Typically, people come to OpenAPI after they've got an API. They want to describe an old API. They want to get this API under management. And they'll do this. They want to first, you know, they want to get it down on paper, if you will. And so they've got this API. They'll use tools like curl or postman or a bunch of others to interact with this API. And then they're going to record that into a document that describes those interactions. Now, tooling is getting more and more advanced where this can become somewhat automated. As you interact with your API, you can take that and it'll generate an open API definition or a YAML file. Once you've got that, you can sort of clean it up and prepare it so that it will match the API that sits on a server somewhere. Once you've got this YAML file which describes the details of some, possibly all, requests and responses that come out of your server, you can then generate documentation to say, okay, well now I can generate this documentation. Now I can see my API. I can also see what's in it at a glance, and then I can go beyond that. So once I've got my API described in some formal specification, which is what OpenAPI is I can now use tooling to really leverage that and take it to the next level of putting this in my CI CD pipeline to check if my API changes or to generate SDK clients. Once I've got that phase, which is typically the way people are introduced to OpenAPI and Swagger, I can start designing APIs before I build them. That's the frontier. Let me describe it. Let me tell you what an API could look like, and then let's go and build it from that spec.

DAN_SHAPPIR: So if I would like want to contrast open API with let's say, my GraphQL. GraphQL is usually used in kind of like a green field type project. I'm going to be building a new API. I wanted to codify, maybe I'll use GraphQL. What you're describing is I already have an API in place and I want to codify it. I want to document it. I want to kind of get it under control so that going forward, I won't make a mess of things and introduce all sorts of contradictions. So if I understand correctly, what you're saying is, I can use this process and this method of describing, let's call them HTTP based APIs or even RESTful APIs. And then I'll record what I have, I'll codify it, I'll document it and I'll set it down in stone as it were in a bunch of YAML files. And from that point on, I can ensure that I don't introduce contradictions, that I have proper testing, that if I want to develop a new client for these API, I'll be consistent with it. If I want to rewrite my server, I know that I'll be consistent with the APIs that I already have. And going forward, If I want to enhance the API, I can do it in a quote-unquote sort of a standard way. Is that, am I more or less echoing what you said? 

JOSH_PONELAT: Yeah, I think so. Let's, let's put GraphQL to a side there for a second. We can revisit it for sure. But what you've described is, you know, the, the first stage or the first interaction is, you know, let's get this API formalized, codified, if you will. But where it really gets exciting is when you start designing ahead of coding and this format gives you this possibility of saying, getting feedback on an API, which as we found today, APIs can live a long time and their commitments, especially with your public APIs that sit out there and say, this is our API, it cannot easily be changed. So we want to get it somewhat right ahead of time. And we've also got this medium of connecting front-end and back-end developers. So you can code your back-end independently of your frontend. Now you want to keep those feedback loops pretty tight either way, but you can code against a contract of an API, right? So you know the API, so now you can just code against that and you can put mocking on either side of it. GraphQL is, it's definitely used in in Greek fielding projects, but it is an entirely different schema. It is a protocol as well as tooling and things like that. Open API describes HTTP. It doesn't introduce anything new to HTTP. Whereas GraphQL, you go through one endpoint and you describe your data as a series of nodes on a graph, which is pretty cool. And then they've got a custom schema or it is schema, right? It's a string that you send into a GraphQL server and it will take that string, break it down into some AST, gather the data and send it back to you, which is great for bandwidth-constrained clients. Because you're asking for a small set of data in a compact way, and you're getting just that data. HTTP has a bad rep for, well, we've got the restful semantics of A, B, and C. And so if I want to get all the data I need for my client, I have to make several requests, sometimes picking back off older requests. I get one request, and based on that, I'll make another request. And there's definitely ways of getting the benefits of GraphQL into HTTP, several interesting projects around that. But coming back to what OpenAPI is, it doesn't add anything new to HTTP. It is just a way of codifying it and allowing tooling to leverage that document, that YAML file, to be able to do all sorts of things. 

DAN_SHAPPIR: So it's kind of like schema for schemas.

JOSH_PONELAT: Yeah, that's definitely very meta and I like it and that's pretty accurate too. Because OpenAPI describes how you can describe your API, but then you need to describe your API, right? So that's a schema for your API. A schema of schemas. 

CHARLES MAX_WOOD: The thing that I'm seeing here is that if you put the schema up and let's say you put the specification together in a YAML file, people can grab it, they can look at it. I'm assuming you put it in a YAML file so that a program can actually pick it up, right? 

JOSH_PONELAT: 100%.

CHARLES MAX_WOOD: to specify a driver for the API is where I see people using this. So yeah, what does that use case look like? 

JOSH_PONELAT: I'm glad you brought that up because one of the, when Swagger was smaller, it was an API schema for humans and computers, right? So YAML was chosen because it's somewhat easier to write than JSON, which is very strict, right? If you have a trailing comma on JSON, it blows up and you start wondering why that's the case, whereas YAML is far more forgiving. But of course you want computers to be able to understand it, break it down. So yeah, it is, it is a format to share. Once you get the YAML file, sure you could read it, but you know, it's, it's much more convenient to get a tool to generate something pretty for you. Right. So you get a nice little website or webpage generated from the YAML on the fly and that you'll, you'll end up consuming, or you'll use the tooling to generate those SDKs or server stubs. Again, all of the circles around this one document that simply tells you how the API works. Maybe not the connecting points, the semantics of, oh, well call this operation and then this one. And then when you have all those done, you'll have done a bank transaction. It's more on the concrete inputs and outputs, which goes a long way. 

DAN_SHAPPIR: So I assume that these days a common use case for these YAML files would be to generate a DTS file or something like that.

JOSH_PONELAT: I'm going to be ignorant here. What's a DTS file? 

CHARLES MAX_WOOD: I was going to ask too. 

DAN_SHAPPIR: DTS file is a definitions file for TypeScript. So it basically specifies an API that you can use from TypeScript and then you will get all the auto-complete and stuff like that in your development environment. 

JOSH_PONELAT: And that's a fantastic use case. And yes, that is one of the ways that OpenAPI helps. So you generate a client in TypeScript not only does it generate the TypeScript definitions, but you've also got the SDK itself, right? The code that'll execute. So in your IDE, you can explore an API by simply hitting tab, right? Which is fantastic. I mean, that for me is like Nirvana almost, because now I can sit there and say, oh, I wanna execute this tab, these are the list of operations, what data do I need, tab, tab, you know, these are the fields and I can hit go. 

CHARLES MAX_WOOD: Are there use cases other than the tooling then that we're seeing with this?

JOSH_PONELAT: Yeah, so one of the, I mean, it all comes down to tools because you want computers to process it. But in addition to documentation, which is probably the leading use case, you want to show developers how to use your API. And you get that almost for free because once you got your YAML file, bam, you've got a website and there's several great projects out there that'll do this for you. Then we've got our SDKs, our service stubs, but the other use case, if you will, is the oversight of knowing that your API is consistent in style is now becoming more and more popular. The fact that all your operation IDs have camel case, which a lot of larger corporations are big on because that consistency gives them a strength to move developers around that gives them the quality that they're looking for, that their API doesn't look completely different. There's the oversight that comes from knowing breaking changes. Adding a query parameter is fine the JSON object might not be so great. And so if you've got the previous definition and you update to a new one, you can now tell in your CI-CD pipeline if this is now a breaking change. So all of these oversights come from knowing your API. And OpenAPI is that thing. You know it once you've got it written down. And I'm hoping that there's gonna be a whole bunch of more things that we haven't thought of to add to this because yeah, knowing the thing is having it described, I guess.

DAN_SHAPPIR: Given that we've spoken all this time about OpenAPI, what are we going to bring up the topic of Swagger? Because we talked about how Swagger is distinct from OpenAPI. So what is it and what does it mean? 

JOSH_PONELAT: Now's a great time to bring it up. So again, looking back at the history, everything was Swagger up till a point. And then they took the specification part out and they donated that and that became OpenAPI. What was left was all the tooling, the initial tooling that helped make Swagger useful. It wasn't good enough that you can describe an API. You want to get that documentation and those client SDKs. There's a whole bunch of tools with the word Swagger in them. That's what Swagger is today. When we refer to Swagger, we're referring to those tools, of which Swagger UI is probably one of the most popular because it was the oldest and got bundled with all the servers. You would have a server and then one of your endpoints would serve this API documentation for free because of the way it was configured. And you've got Swagger Cogen, which is the thing that takes a definition file, a YAML file, and it generates all your, it can either generate static documentation, or the SDKs, the clients, the mock tests, all that stuff, because it's a templating system. And there is validators on your definition files, you wanna make sure your definition file is valid, little things like that. There's several bunches. Those are Swagger today. And OpenAPI simply refers to the specification, how to write YAML files. 

DAN_SHAPPIR: So Swagger is the tooling and the open, an open API is a specification. That's a distinction. 

JOSH_PONELAT: Correct. More specifically, Swagger is a finite set of tooling. A lot of tools now are, you know, becoming open API tooling in order to adopt the more open name, if you will. So Swagger is a very specific set of tooling, most of which is still curated by, by the company that took on Swagger. And that's SmartBear. 

DAN_SHAPPIR: When you say curated, you mean these are open source tools? 

JOSH_PONELAT: Correct. The vast majority are all open source. And they live in GitHub. And they've got communities around them. 

DAN_SHAPPIR: I understand. 

CHARLES MAX_WOOD: I keep looking at this. And I'm thinking, OK, well, people can use this to automate the process of using the APIs. And now we're talking about some of the tools. Are there tools out there that test APIs, or do pen testing on the APIs, or things like that based on the open API? 

JOSH_PONELAT: We are seeing tools spring up like that all, I wanna say all the time, but the more niche ones come and go. A lot of companies have in-house tooling. They do their own form of pen testing, if you will. Testing APIs is quite tricky. You can certainly do input-output tests, sort of as, if I give these inputs, I expect these outputs. And validation is a form of testing where you can put this during your runtime so that requests coming in will go through this validation layer to make sure that it matches the type that OpenAPI is already described. But actual testing of saying, yeah, my API is up and all the operations in it work as expected, that's a little harder because there's a lot of semantics involved with that. But there's definitely more and more interesting use cases coming out of OpenAPI that we're seeing right now. The big one is around oversight making sure your APIs look and feel the way you want them to, especially when you have hundreds, sometimes thousands. 

DAN_SHAPPIR: Can you give a more detailed example of what you mean by oversight? 

JOSH_PONELAT: So oversight, for me, are those two things of breaking changes, so diffing between APIs, and making sure your description of your API is consistent, whether that's you've got a... Every object has a 400... Or every response has a 200 request. So in order to ensure this, you have these systems in place that look at the YAML files and do linting on them. So that's oversight for your CIDC pipeline. So you can now see how consistent your APIs are. 

 

This episode is sponsored by sentry.io. Recently, I came across a great tool for tracking and monitoring problems in my apps. Then I asked them if they wanted to sponsor the show and allow me to share my experience with you. Sentry provides a terrific interface for keeping track of what's going on with my app. It also tracks releases so I can tell if what I deployed makes things better or worse. They give you full stack traces and as much information as possible about the situation when the error occurred to help you track down the errors. Plus, one thing I love, you can customize the context provided by Sentry. So, if you're looking for specific information about the request, you can provide it. It automatically scrubs passwords and secure information and you can customize the scrubbing as well. Finally, it has a user feedback system built in that you can use to get information from your users. Oh, and I also love that they support open source to the point where they actually open source Sentry. If you want to self-host it, use the code dev chat at sentry.io to get two months free on Sentry small plan that's code dev chat at sentry.io. 

 

CHARLES MAX_WOOD: Yeah, that's one thing that I like, right? Is that, you know, as we get into programming languages, we get used to sort of the overall schema of the way things are put together and so yeah, it kind of has a consistent feel and if something doesn't match the flow of the language. It kind of sticks out whenever we have to use it. And so, yeah, I like that as kind of an audit of your API to go, okay, I'm looking at the entire spectrum that we have here and that one doesn't fit. Right. And so then I can go in and I can say, yeah, we need to fix that. So, you know, the parameter names don't line up or the parameter names indicate one type over another, or, you know, the naming just, you know, we've got restful all over here. And then we've got this weird outlier for whatever reason. How can we make it line up? 

JOSH_PONELAT: Exactly. It could be as simple as I don't want to see a URL that includes the word execute on it, right? Because that indicates some sort of RPC thing that sort of breaks our restful ideology. And consistency gives you a lot of freedom, right? If you know that without researching this one out of a hundred APIs, that it's going to behave and look and feel the way you expect, that gives you a leg up in consuming that API. 

DAN_SHAPPIR: Can you do like a little bit maybe of a name dropping? I mean, can you give examples of like APIs or services that our listeners might be familiar with that you can name that currently already use OpenAPI? 

JOSH_PONELAT: Sure, so the OpenAPI team itself is like all the big boys are in it from Google through Amazon. Microsoft has got two guys on it. Google's definitely in it. Amazon uses it for all of their API gateway stuff. They've got... So, here's another use case. That's a great way. Amazon, if you've ever worked with their API gateway, you've got to describe the runtime thing that your requests come in and then you tend to link those to Lambda functions. So Lambda functions are these little tiny little programs that you can put in the cloud, if you will. And so, Amazon has the system. In order to make some of those connections, you can use vendor extensions on your open API YAML. The YAML file you described describes the HTTP part. Great. But what if you wanted to add some custom stuff in there to say, well, this operation, this one should be linked to that Lambda function, or this operation has these constraints on it, and I should flag every time this operation is called, I want this red flag to pop up in my system. Now you can go in there and you can add this to the YAML file where your API is described. So these consuming services can now know more information about operations and your API in general. Amazon's gateway is a great example of this or AWS's gateway. Microsoft is a big proponent of OData. It's another format or more constraints on the way your data is formed formalize it. There are different HTTP-based schemas out there and they wanted to get the standard, right? That tends to be what OpenAPI is, the standard agreement on that. 

CHARLES MAX_WOOD: Now you wrote a whole book on this. You know, we're sitting here and we're going, okay, you know, I kind of get bits and pieces of this, but what's kind of the flow of the book? You know, how does it explain this and how does it guide people through being able to use these techniques and tools?

JOSH_PONELAT: Cool. So yeah, I'm writing a book. It's not complete yet, but the book I'm writing, Designing APIs with Swagger and OpenAPI is a primer to give you value out of using OpenAPI. So we start with describing APIs today. So a lot of the HTTP APIs, they exist today and they're a little bit of the Wild West of knowing what's in there. So the very first thing is let's get it on paper. Let's put it down so we can use it. And then building on from there, we look at how we can design APIs without having written code first. What's the process around designing your RESTful, hopefully RESTful APIs or HTTP-based APIs before you write the code? And what sort of feedback loop can you get out of it from getting your server stubs up, getting a front-end engineer to start coding against that, and getting that feedback that can tie back into your YAML file that you use as the center of this little universe. And then lastly, in terms of the flow of the book, so part one, let's describe the API, part two, let's design APIs, part three takes a look at, well, how can I get some real juice out of the system? Something similar to what AWS's API gateway has, where they've added data into the operation. How can I look at building my own tooling around OpenAPI so I can get more mileage out of it you know, for my own purposes, things that haven't been built yet. 

CHARLES MAX_WOOD: I think you're publishing it with Manning. So it'd be on the Manning early access program. 

JOSH_PONELAT: Yeah. You should definitely go check it out. It's a thing. They call it meep Manning early access. Yeah, that's the one. 

CHARLES MAX_WOOD: I know. I always feel funny saying meep. Go meet that folks. 

JOSH_PONELAT: Exactly. So yeah, it's definitely out there and part one's done and, and we're going through part two with part three pieces as well.

DAN_SHAPPIR: Yeah, I was looking through it before this podcast and it looks really good. So congratulations on that. 

JOSH_PONELAT: Thank you. Appreciate it. One of my big driving factors here is first to give value at it because that's where any conversation starts is, you know, it needs to provide you with value. But secondly is to see how it can evolve. I'm a real big proponent of schemas for things. You know, once we've got a schema, once we've described something to some sort of formal spec. You know, the world is our oyster. There's, there's so much tooling that is yet to be designed around this. It's sort of another dimension on top of it. You know, once you've got, you can have an API and once you can start putting an API in a box, you know, which you've described it now and you can start moving and interacting with that box. Right. It becomes another dimension of operating on APIs as data. And that excites me a lot. 

DAN_SHAPPIR: So if we said that OpenAPI is a schema on a schema, then your book is a schema on a schema on a schema. 

JOSH_PONELAT: Right, we need to get those little indexes up there. I like that a lot. 

CHARLES MAX_WOOD: It's turtles all the way down, right? 

DAN_SHAPPIR: Exactly. 

CHARLES MAX_WOOD: Oh, very cool. So what aspects of this have we not asked about or talked about? 

JOSH_PONELAT: OpenAPI and Swagger, you know, the disambiguation is still a thing and I'm glad we get to chat about it because OpenAPI, you know, that's, the spec is the heart of it at the end of the day. And it's important to encourage people to describe things. Maybe it's not their APIs, it's something else, but putting things down on paper is an incredibly powerful thing. The tooling around OpenAPI today is very mature. We're seeing it grow. The OpenAPI specification itself is versioned. So we'd had a lot of people will see Swagger 2, which is now supposed to be called OpenAPI 2, and we're currently on OpenAPI 3, which brought in a huge power to you as a writer of API definitions to be able to describe more and more things. And that specification is being worked on constantly. So the 3.1 release is gonna bring an even more powerful features to it. So it's something to keep an eye on, especially as tooling catches up with those features. So yeah, versioned of the spec is important to know because a lot of tools will support two, perhaps not three, but the maturity of two is like years and years old. RetroDiv 3 is about, I want to say, a year and a half old, but the tooling is definitely fast on this. Thanks to all that effort and open source of getting the stuff up and going. 

CHARLES MAX_WOOD: Makes sense. I'm also curious about some of this. It seems like we're kind of in this season where a lot of things are evolving with APIs. We've got REST, and then we've got GraphQL, and then we've got gRPC, and we've got, I'm trying to remember. There were a couple of other ones that looked really, really interesting. One of them started with a V that was, anyway.

JOSH_PONELAT: Well, there is one there I'll stop you on which is quite interesting. It's Hypermedium. So Hypermedia is the purists for rest, right? 

CHARLES MAX_WOOD: So yeah, you really want to do rest. We've talked about that for years on Ruby Rose. 

JOSH_PONELAT: So that's definitely getting some traction as well, getting Hypermedia and how that ties into HTTP, how it really leverages the full power of HTTP, just to complete the list, which was... 

CHARLES MAX_WOOD: Yeah. driving toward is where's all of this taking us, right? We get better tooling, we get better ways of specifying APIs, and then maybe we get better APIs. Do we wind up going to a place where this actually impacts, maybe there's a hyper hypermedia API or something like that that comes out of this where it's like, look, this methodology makes it really easy to specify in this way and. And it makes all of these tools just kind of seamless, right? Where I don't even need the Twitter driver anymore. I just need an open API driver. Right. Are there other directions where this is heading? 

JOSH_PONELAT: So I think the direction is to, to treat API is as first-class citizens by turning them into data. And the idea being once we've got them in data, we can operate on them just like any other form of data. And, and that's sort of the direction we're going with here where We've got schemas and we're describing things, different cases of them. gRPC, what it did was it brought something called protobufs, which are a fantastical compact binary format that is great for speedy protocols, where HTTP is quite large and it's still text-based. And it took that and it added a schema to it. And by that very merit alone, it's taken gRPC into so many more applications because now you know how to use it. Now you can know how to use it by being able to share it, by being able to critique it just by looking at the schema. Once you can treat APIs as first-class citizens as data, you get to look at the whole world as a different way. And just showing how that GRPC, which took protobufs, great protocol, and just added a schema on top of it, and that's the power behind it, getting in front of people's, into people's systems by leveraging that which I don't think would have been possible without having a schema. GRPC's power comes from being able to generate your service and clients, you know, so that you can, you can talk this, this protocol buffer, which is very hard. It's very compact, very binary. So you want to automate that. And that's from treating the API itself as, um, as a first-class citizen. So that's the direction. I think all of these things are working their way towards. 

CHARLES MAX_WOOD: That's really, really interesting. And it's always interesting too, just to see you know, for all the things that you're talking about that you see coming, some of the unintended things that are going to going to come out of this that are going to make a difference for people too. 

JOSH_PONELAT: Right. That's the exciting part. The stuff that we haven't, you know, thought about yet as a result of these innovations around the world and API's and, and other things too. If you think about the, you know, API's, do we want more of them or do we want less of them? Once you weigh that question and think, well, API's are good. You know, they, they allow me to to build things that I couldn't build before. Right now, because of all the APIs that exist out there, I can send SMSes, I can make phone calls, I can spin up images in the cloud at a whim. And so yes, we want more APIs. So anything that helps us get more APIs, I think is a good thing. It allows us to innovate on whole new levels. 

CHARLES MAX_WOOD: So do you know when the book's gonna come out? 

JOSH_PONELAT: I think it's coming out next year, mid next year, I think. I'm not actually sure on the end date. I'm just writing at heavy pace because it's interesting stuff. And I'm sure my publishers will shout at me to narrow it down and give more concrete things like that. But I think it's planned for mid-next year. 

CHARLES MAX_WOOD: Sounds great. I'll see if I can find a link to it on the Manning Early Access. And hopefully people can get their hands on it because I think that would be awesome. Is there anything else Dan that you feel like we need to talk about? 

DAN_SHAPPIR: No, I think it's pretty well covered from my perspective. 

CHARLES MAX_WOOD: All right. 

 

A few years ago at a JavaScript conference, I was approached by Nader Dabbit. And you might know him from the React Native radio podcast. He's also a developer evangelist for Amazon. And when he came to me, we had a conversation about React Native. And the thing that I love about React Native is that it's approachable, it's web technology, and it's cross-platform. And it makes a lot of things really easy for developers to jump in and do interesting things on mobile with JavaScript. So we've had this show now running for several years, React Native radio, where we interview people about the React Native ecosystem, some of the things that are coming out and react and how they affect mobile and other options that you have for mobile development. So if you're doing mobile development, you're doing it in JavaScript, you're looking for a good option, or maybe you're just trying to stay current with react native, then go check out react native radio at reactnativeradio.com. 

 

CHARLES MAX_WOOD: Well, then should we go ahead and do some picks? 

DAN_SHAPPIR: Yeah, let's go for it. 

CHARLES MAX_WOOD: All right. I usually let our hosts go first, but my wife is going to walk in here literally in like two minutes and, uh, she's going to be like, okay, it's time to go. My three-year-old has a Halloween program for her preschool class. So, 

DAN_SHAPPIR: Oh, that's so nice. 

CHARLES MAX_WOOD: Yeah. We're, we're definitely doing that. We're, we're recording this on Halloween. So happy Halloween. Yeah. 

DAN_SHAPPIR: None of us are wearing any sort of a mask. 

CHARLES MAX_WOOD: There is a mask on my hoodie. It's a Ruby Rogues hoodie. There's a mask on our logo. In fact, I should just throw this out there. So if you go to teespring.com slash stores slash dev chat.tv. If you go to the show notes, you can get it. And I'll probably also have some link like a shirts.devchat.tv or something you can hit, but yeah. Um, I'm putting up shirts for the different podcasts. People can, you know, go and buy shirts. I get asked about this periodically. Where do I get stuff? I'm like, well, 

DAN_SHAPPIR: I want stuff, Chuck. I want stuff. 

CHARLES MAX_WOOD: So I'm just going to put that out there. Last time we ran campaigns for this, which was a few years ago, I bought this hoodie. And so the one I'm wearing as we record this is the one that's up there for set. Well, not the exact one, I guess, but same design, same, you know, manufacturer and stuff. We also have women's tees. So if that's something that you're looking for, we're going to put that up too. I've had a few people ask me about Patreon and things like that, as far as being able to support the show. So I'm working on getting that up. So yeah, I'm going to throw that out. Another quick pick that I have and this is something that I've used for a while. I just don't pick a lot of the tools that I use because I don't think about it. It's kind of become an everyday thing. But one of them is Busy Cow on my Mac. Really loving that. It's a terrific program. Makes the calendar thing really, really easy. I think I've added like 20 something calendars to it because I'm insane and because we used to have a calendar for every show. That's part of the deal. We don't anymore. Now we just manage it on like two or three Google calendars. So I'm going to pick that because that's been really great. Anyway, I'm going to go ahead and drop off the call and I'll let Dan and Josh do their picks. And then we will have another show next week. So max out everybody. 

DAN_SHAPPIR: Enjoy. Have some fun with your daughter. 

CHARLES MAX_WOOD: Will do. 

DAN_SHAPPIR: Okay, Josh, do you want to pick your picks?

JOSH_PONELAT:  So you'll have to help me out here, Dan. What are we picking? What's the field of? 

DAN_SHAPPIR: It could be any sort of pick you like. It doesn't have to be to do anything with software. Actually my picks have nothing to do with software. If you want, I will go first and I'll give you a few more minutes to think about yours. So I've been running over the last couple of episodes through all sorts of what I consider to be really, really good fantasy books from authors that have kind of, um, dropped off most people's radar. So they're less known given, uh, you know, everybody's familiar with, still familiar with Tolkien and obviously with Game of Thrones and George Martin and all these sorts of books. So I'm running through a list of less well-known books, which I still consider to be incredibly awesome. So this time I'm going to mention a series of books called Saga of the Pliocene Exile. It's by Julian May. She's an awesome author. She wrote these way back in the 80s. It's a series of four books. It's not exactly fantasy. The wrapper, the wrapping is actually more like science fiction. It's people like living in the future where it's a very advanced society. We've encountered aliens and the humans are part of this galactic type federation. And some people like don't fit in because they're outcasts and just can't handle this modern existence. So when there's this sort of a doorway that's opened into six million years in the past on Earth and it's just this one-way doorway, so once you go back there's no return. So you go there and then you have to stay there and the people don't really know what's back there except that it's like prehistoric Earth. So a lot of these sort of people decide to go back there and what they don't want to spoil anything, but it kind of becomes a fantasy sort of a story once the people go back there. And it's not really magic, but it's like telepathy taking a form of magic. And, you know, I'm not describing it as well as I would like, but it's a really incredibly awesome series of books, and I really, really highly recommend them. And yeah So that's going to be my pick for today. And I'm going to put in the link to the Wikipedia post describing these series of books. And now over to you, Josh, if you have your picks. 

JOSH_PONELAT: Cool, Dan. Well, I don't think I can top that. That sounds amazing. And as a reader, I need to ask a big question. Is the series complete? 

DAN_SHAPPIR: Yes, the series itself is complete. Like I said, it was written back in the 80s. She later wrote a whole bunch of additional books about different periods, like I said, because the beginning of the story actually happens in the future before they go back to the past. So she then kept on writing more books about the future era. And I've not read all of them, so I don't know if that's complete. But the books that describe what's occurring like six million years ago in the Pliocene era, that's actually, like I said, those are those four books and it's wholly self-contained and the story is done. So it's not like what would happen in a lot of series of books a day where you start reading, you get all excited, and then you realize that the story's not come out yet and maybe never will, hinting George R. R. Martin. And no, so in this case, it's done, it's self-contained, and you'll totally enjoy it just reading those four books. You don't need to read any other of our other books. 

JOSH_PONELAT: Thanks Dan, that's important for me as a reader. Reading a series and getting stuck on a book and waiting for that next one is just so disappointing and you know Kudos to the authors who go into the effort of writing these stories that are so entertaining. But wow, I feel like I need to take on series completely at a time. All right, so Picks so while you were chatting I I had to think about things that I use quite regularly and i'm going to list two picks. The first one is I discovered as part of writing this book. It's called ascii doc. And for those who don't know it, it's like Markdown, but kind of on steroids. And it's really cool to generate PDF files if you're comfortable writing Markdown files. So I would definitely go check that out. And my second pick is going to be a little command line tool and it's called FASD. And I, I'm a console junkie and I often, you know, love bouncing around on my terminal, but one of the stickiest points is navigating from one folder to the next. So this little FASD tool, I used to jump to folders, usually using just part of their name. So long as they're in my ZHS or bash history, it'll make an educated guess and it'll get me there. So I definitely, if you enjoy messing around the terminal, this is a godsend. 

DAN_SHAPPIR: Yeah, it sounds really awesome and I'll definitely check it out. I use the terminal a lot and I wasn't familiar with this tool, so thank you very much for that. Okay, in that case, I think I'll wrap it up, wrapping it up for the first time by myself without Chuck. So thank you all for listening to JavaScript Jabber and over and out, bye bye. 

JOSH_PONELAT: Happy Halloween. 

 

Bandwidth for this segment is provided by Cashfly, the world's fastest CDN. Deliver your content fast with Cashfly. Visit c-a-c-h-e-f-l-y.com to learn more.