In today's episode, they dive deep into the world of API documentation and best practices with Svyatoslav Kryukov. He is a Backend engineer. He discusses the critical importance of creating detailed specifications for RESTful APIs and recommends an insightful book for those eager to learn more. They explore the intricacies of generating documentation using DSL and tests, highlighting the pivotal role of YAML in this process. They share their methodology for writing comprehensive specifications before team discussions and the subsequent generation of development files. They also touch on the benefits of making these specifications available in a user interface through tools like Skooma, Rspec, and minitests.

You'll hear valuable AI tool recommendations, and plans for an AI and Ruby summit. They also delve into their struggles with focusing on reading and share efficiency tips using AI-based tools like Speechify and Kagi search. They cover various aspects of using OpenAPI and Swagger tools, addressing challenges in fake data modeling, and the importance of user feedback in API design. They also discuss the distinctions between OpenAPI and Swagger, the history behind these tools, and their role in code generation and AI workflows.

Socials

Charles Max Wood [00:00:04]:
Hey. Welcome back to another episode of the Ruby Rogues podcast.

Charles Max Wood [00:00:08]:
This week on our panel, we have Valentino Stohl.

Valentino Stoll [00:00:10]:
Hey now.

Charles Max Wood [00:00:12]:
I'm Charles Max Wood from Topten Devs. We have a special guest this week, and that is Svyat. Do you want to just tell us who you are and

Svyatoslav Kryukov [00:00:22]:
Sure. Sure. So, I'm backend engineer at EvoMashions and I really love working with all the exciting technologies using Ruby Next, like, to make Ruby look like Golang, for example, writing parsers, running Ruby WASM in browser with runruby.dev. And Charles, you decided to bring me here to talk about API documentation. Right?

Charles Max Wood [00:00:48]:
That yeah. That's my favorite topic. I'm I'm every week on the show, I'm like, we're not talking about API documentation. Why am I here?

Svyatoslav Kryukov [00:00:57]:
Let let's fix that.

Charles Max Wood [00:00:59]:
Yeah. Let's let's do it. So I I have to say, it seems like documentation is the thing that everybody just kicks the can down the road with. Right? I'm also gonna point out, so not this contract that I'm on, but the contract before, I was working on some, AP no. It was 2 contracts. Anyway, I was working on basically integrations between 2 APIs. Right? It's like, hey, get the information out of here and sync it up with the information over here. And, I have to say, API documentation is a con concept that some of these folks could have worked on.

Charles Max Wood [00:01:38]:
Let me just put it that way. The people who documented the APIs, it's like it's like, okay. Yeah. You're telling me all these fields, but, you know, it doesn't actually tell me how to use it. Right? And so I wind up trial and erroring my way through sending him a date or a string or, you know, the structure of the data I have to send back. So, yeah, so how do we do it better?

Svyatoslav Kryukov [00:02:03]:
Yeah. So I I was, in the same position, and I was one that did that to you. Not not to you, but, you know, to different developers, with poor documentation. So, if you yeah. Partially. So, yeah, let let me just tell you tiny story that covers up, like, the whole of my career, like, like, past 10 years. I'm doing API APIs. So I started my Ruby career in a small, health care start up, and we had a simple Rails, API only, application on the back end and 2 native mobile apps.

Svyatoslav Kryukov [00:02:45]:
So only 3 of us, no seniors, no rules, no documentation. And everything went pretty fine, until we started developing fairly complex features. And quite soon, we understood that developing, features spread across 3 different platforms without any API documentation is quite painful. So we started documenting our API using, new and heap app called Postman. So you might use that.

Charles Max Wood [00:03:20]:
And Postman saved my life on the the scenario I was talking about. Because I could rapidly go, this, no. This, no. This, no. This, no. Hey. It worked. Oh, it kinda worked.

Charles Max Wood [00:03:32]:
This. Anyway.

Svyatoslav Kryukov [00:03:34]:
Yep. Yep. Basically, that's what we did. So you can save those, actual, like, tries and, reuse them later. So that was our documentation at the at the moment, and it went again pretty fine until we forgot to update it too many times. So and our personal collection become constantly stale. And, with that, we discovered Rswag. And Rswag is a gem that extends, our spec with a special DSL and uses that to generate an open API documents, which then turns into beautiful live documentation.

Svyatoslav Kryukov [00:04:18]:
And that's basically my dream came true because, you know, we generated something like postman collection right from our our spec tests.

Charles Max Wood [00:04:31]:
Mhmm.

Svyatoslav Kryukov [00:04:32]:
That's a miracle. And we don't need to think about API docs. They're just there and always up to date. That's cool. So the resulting development process, it looked like this. So I developed a v zero version of a new API feature that we need. I tested that with Rswag generated documentation, and passed that to mobile devs. Then they use the documentation and they implement their own like, interfaces.

Svyatoslav Kryukov [00:05:04]:
And sometimes they they ask me to fix my a API. And since it's Rails, I do that pretty, like, quickly. Right?

Charles Max Wood [00:05:12]:
Mhmm.

Svyatoslav Kryukov [00:05:14]:
The need to rewrite tests when I do those changes was kinda irritating, but still it it worked pretty fine. Until the time we decided to, add a medication reminders feature to our app. To support that, I designed a model that added 2 fields, like start date and end date. And, I made end date nullable since for for cases when reminders should never stop because, you know, indications. Mhmm. So, with with that, weeks later, I'm testing the resulting application, the mobile application. And what I'm seeing is a reminder with the end date in the year to like 4,001, which is kinda strange to see that. And It's

Charles Max Wood [00:06:08]:
coming up fast.

Svyatoslav Kryukov [00:06:10]:
Yeah. Apparently, iOS developer decided to mark those infinite reminders with a date distant feature, like distant future. And that thing, serializes to the year 4,001.

Charles Max Wood [00:06:25]:
Wow. Okay.

Svyatoslav Kryukov [00:06:28]:
Since mobile devs in my team, they were better team players than me. They discussed that decision, actually. And Android developer did the same. But in Java, Serral's version become the year 1999.

Charles Max Wood [00:06:43]:
Oh, wow.

Svyatoslav Kryukov [00:06:46]:
So, that was a sign that something went complete completely wrong with our workflow. Right? And the problem is we had the documentation in place, and the end date was marked as knowable in that documentation. So and if you think about that, it's really logical to use, like, now for for end date that is unknown at the moment because it can be anything that user can add, like, dates there and stop, taking those communications, like, tomorrow or in 2 weeks or in 2 years, whatever. So Zeno is like, it's like by the book. Like, it's like the description of null. And yet mobile devs decided to do that horrible wrong thing. So, but if you think about that, actually, it was me who was wrong. Because my attitude towards the documentation was completely wrong.

Svyatoslav Kryukov [00:07:47]:
I thought about that as a, like, artifact, and I didn't write a, you know, like, proper description to explain why the end date is movable. And we never discussed that edge case with the team, or maybe we did, but we lost that somewhere in this lecture. So Rspec didn't help me to become a better developer. Thankfully, about the same time, I bumped into a talk about the computation first approach from, rails conf 2018 by Ariel Kaplan. And after that, I I finally realized that documentation is actually the core of my API and not just the leftover. So now I I honestly, I I I can't imagine developing APIs in the other way.

Valentino Stoll [00:08:39]:
So let's let's dig into this. Like, what do you mean by Yeah. Documentation first? Like, I know, you know, folks can listen to Ariel's talk, you know, after this, because it is pretty great. But can you sum up just like what do you mean by documentation first?

Svyatoslav Kryukov [00:08:56]:
Sure. So with documentation first, you start your work by writing the specification for the resulting API. And that might sound like, the most boring thing in the world, but, actually, that's what the best programmers do when they design their code. Mats doesn't start with the implementation of a new feature for the language. He discusses the interface first. And in that discussion, that that discussion itself, it it might take much more time and effort than the implementation itself. And probably that's why we'll offer Ruby. And maybe that's why we have next to non breaking changes in our language.

Charles Max Wood [00:09:45]:
Mhmm.

Svyatoslav Kryukov [00:09:45]:
So, like, another example, like, imagine silently preparing a giant PR to bring something cool to your project or say to open source project. And let's say you prepare the PR for rails active model, like bringing something really cool and giant and awesome. And you opened it, and you got a review from someone from the core team. And they say that, actually, you know, the resulting interface, it's not in line with the real standards. Like, we have all those different ideas already here and there, and they have, like, all the examples and clear action points for you. So it's not a rude no. It's an actionable thing. But in result, to get your PR accepted, you need to rework everything from the scratch.

Svyatoslav Kryukov [00:10:44]:
And I don't know. Do you feel the pain right now? Because I definitely do. What would be better, to create an issue and discuss interface first? Right? That's basically the documentation first approach. So let let's give, another example with an API since we are talking about APIs. So you are working on a new feature. You design the models, like services, commands, form objects, whatever you use, And you tested all of that, of course, and you pass the result to your team. And apparently, your, like, pagination, filtering design, whatever, it went out of sync with what front end needs. And for some of these reasons, they are locked to use that specific know, format because of framework or vendor, whatever.

Svyatoslav Kryukov [00:11:34]:
So it's your fault and you must drop everything. And all that beautiful, well tested, perfectly designed, reusable code that you did, You just need to remove that and start from the scratch. So maybe, like, I know how many listen listeners, screaming in agony right now that that would never happen to them. Like but if there is no process, you might discuss pagination, but forget about filtering, or miss the fact that front end needs that specific interface and so on. We are all just humans or machines, and we need processes to guide us. Right? Another another idea is, a, no one ever complained about my docs, so they are good probably. Charles, you you had your your story bit about documentation. Have you ever told the other side that their docs are bad?

Charles Max Wood [00:12:42]:
Yeah.

Svyatoslav Kryukov [00:12:45]:
Cool. So, in in my situation, I worked in a company with 100 microservices and, like, 4 or 5 different server side languages. In that structure, you're always a consumer and a provider of an API. Right? So I saw what happening, when someone uses those auto generated docs, with, like, this idea that it's a simple artifact, and it was just unusable, as you said. Like, it was just a list of function names, instead of human readable descriptions. And, it was just a silent list of hopefully all attributes. And that's not enough to work on. In cases yeah.

Charles Max Wood [00:13:31]:
I just wanna chime in there. I mean, this is the problem I have with, like, our doc as well and things like that is, like, you've got some comment or maybe it'll actually scan the code. It's just

Charles Max Wood [00:13:43]:
yeah, you

Charles Max Wood [00:13:44]:
you don't get the whole story. Right? It's like, okay, I've got a list of parameters and maybe an endpoint to hit or something, but it doesn't give me enough to know how it's meant to be used.

Svyatoslav Kryukov [00:13:57]:
True. True. So in case when, it was Python or JavaScript on the other side, I was able to just open the code and read it instead of documentation, and it was fine. But when it was Java or something else, I just started DM developers because it's impossible to, work with. So, Valentina, I I know you use Rspec. How how do you use that? So do you document your your API? Do you use that, you know, DSL extensively?

Valentino Stoll [00:14:34]:
Some teams use it more than others. But, yes, you said, you know, our spec focused realm, where the specs will basic you know, there's another side of this where documentation first is a nice API first, you know, design principle. Another realm of people also think test driven is also a good way of also documenting the code and processes, which maybe not the best case for all API design. But, yeah, it's definitely more test focused than it is, documentation for me.

Svyatoslav Kryukov [00:15:14]:
Cool. Cool. Cool. So, actually, you I I I met people who, do Rspec do use Rspec extensively. Like, they you you can write beautiful documentation with Rspec, but there is other side. Like, do you, like, can you ask your front end team to write those Rspec tests for you? Or maybe in that case, when you work in a company with a lot of back end stacks, are you ready for some parceleton developer to write your tests for you? I'm sorry, but I'm not. So let's use YAML instead. So, yeah, the the documentation first, or you can call it specification first, schema first, design first, whatever.

Svyatoslav Kryukov [00:16:05]:
It's all about that. It's all about bringing the process to your workflow. It will not work if you just silently write the giant YAML first and then write the implementation all by yourself. There's no communication. So, it might be still better because it will work like TDD. You think about, interface first and then implement it. But still, it's all about communication. And your documentation, it's it it must be the central tool of communication with your teammates, with your clients.

Svyatoslav Kryukov [00:16:42]:
And for external API consumers, your documentation is your product. When you're you develop a feature and forgot to document it, you just wasted your wasted your time. Right? No one ever find it in that closed code, even in open source. Like 1% of users will open your code and read it actually and try to find the feature that will never mention, like what was never mentioned. That's cruel, but, you know, that's true. So, with that, I hope I sell the whole idea of the documentation first approach. Like, we write documentation first, and, we can move forward towards, you know, technical details next.

Charles Max Wood [00:17:32]:
Yeah. The technical details is kinda what I wanted to dive into, but, I mean, people have done TDD. Yeah. You you get that thought process ahead of time. You know what you're putting together. And, yeah, I really like the way that you put it where, yeah, your API is your product because for a lot of consumers, it will be. True. So let's get into the technical details then.

Svyatoslav Kryukov [00:17:58]:
Sure.

Charles Max Wood [00:17:58]:
So how do you do it? Is this, like, readmead driven development? You've been mentioning Rswag a bunch too.

Svyatoslav Kryukov [00:18:04]:
Sure. So Rswag is, called first, not called first, test first, I guess, but not the documentation first for me at least. You can do that, documentation first, but it's still much harder to, write our spec, than write than it's right to to write YAML files because you can use editors like and everything. And, again, YAML is understandable by other teams as well. So even your, I don't know, like, manager can read the YAML, I guess, especially in in the editor like swagger, editor, because they can read the documentation, like, the results in documentation, from the start. So

Charles Max Wood [00:18:55]:
So hold hold on. So you're saying to write so you can write it in an Rswag format? And this is just coming from me not having used it. Or you can write it in YAML?

Svyatoslav Kryukov [00:19:07]:
So, yeah, let let's sort of come back in a bit. So, in the documentation first, the whole idea is that you have this standard. You have this, you know, document that describes your API. Mhmm. And in our realm, like, with, RESTful ish APIs, that standard is open API. And Right. By the way, Ruby Rooks has an episode about open API with Josh Bonnelled, and I think we will leave a link to that episode in show notes. So, Josh also wrote a book about open API.

Svyatoslav Kryukov [00:19:49]:
And to me, that book actually looked like 400 pages of design first. He called it design first workshop. So if you want to really dig dive, into that topic and see how it works, like, in in 400 pages, you you can check his book out, because he does a great job giving a very detailed description of the whole workflow. But yeah, so we have this standard open API, which is, a stand standard for describing RESTful APIs, and the resulting document is a, YAML or JSON file. It contains descriptions for all your requests, responses, and it lists like HTTP methods, pass, query parameters, handlers, body attributes, whatever. All that you need. Right? So that's our center of tension, that that file. And next, you can the way you will generate it is the way you will get it file.

Svyatoslav Kryukov [00:21:01]:
That's a different, like, approaches you can work on. For example, you can use r swag, which uses, metadata from your, request tests and also adds a special DSL to, for for descriptions and all that stuff. So in the result, when you run your, tests, it also generates the file, that open API file for you. Or you can obviously just write it manually, and there are plenty of editors and, yeah, you can do that as well.

Charles Max Wood [00:21:42]:
So this is something you can write ahead of time. Right? It's not something that just because because you were saying you you effectively, you know, write your stuff ahead of time instead of, like I said, I'm I'm kind of imagining something like our doc where it, you know, it looks at your code and reads the comments, but even if it inspected the code, in this case, you can just write our spec tests or, things like that in order to say this is how the API should perform, and then it generates the documentation from the DSL. Is that is that what we're looking at here?

Svyatoslav Kryukov [00:22:18]:
Yep. Yep. Yep.

Charles Max Wood [00:22:19]:
But is the DSL through your tests and not from your and not from your code or whatever. So if you haven't implemented yet, fine.

Svyatoslav Kryukov [00:22:31]:
True. Yeah. Yeah. So, yeah, there is also a way to generate open API, from your code. So there are helpers for, like, controllers and all that. So there are different approaches. The problem with those approaches, like when you, for example, use code, like, DSL in your controllers, obviously, you need to write the whole thing. That's a problem.

Svyatoslav Kryukov [00:22:54]:
When you, you can move that to tests. Now you need to write your tests, which which is also sometimes problematic. You still need to, bring all those models and all of that. So even less hard to maintain approach for me at least is writing the whole specification first.

Charles Max Wood [00:23:18]:
Okay.

Svyatoslav Kryukov [00:23:18]:
That's YAML. Yes. That's that's that might be a problem, but at, like, at the same time, you can read it. JavaScript developer can read it. Everyone can read it.

Charles Max Wood [00:23:28]:
So I don't I didn't I don't know if JavaScript developers speak YAML. I think they speak JSON.

Svyatoslav Kryukov [00:23:36]:
That's also the same format. So I know.

Charles Max Wood [00:23:42]:
Right. So so what's your whole process then? So you sit down, you write out the specification. Yep. You port that into a test with our swag, or do you even do that?

Svyatoslav Kryukov [00:23:54]:
So, yeah, if you, go my way, which is writing the YAML first, then you just open a PR, for example, and discuss that, documentation with your team, with your Mhmm. Like, stakeholders, whatever. And they all can see what is happening. You you can bring like, you can, get, like, really fast answers and, gain the information that you missed, while doing that. So, that's the first step. And then you can get the resulting file and start developing your part and front end developers can start developing their part. So it's also like, you can work in the same time, which is a great feature. Regarding the

Valentino Stoll [00:24:53]:
Just real quick. What while you're developing the spec, are you saying that that is, like, made available for people to kind of play with, like, in a a UI kind of way?

Svyatoslav Kryukov [00:25:06]:
Sure. You you can generate. Like, if you set up a PR, like, CI to watch your PR and to develop like, deploy documentation. Why not? So it depends on your workflow.

Charles Max Wood [00:25:21]:
So yeah. So just, yeah, just to kinda dive into this a little bit. So you generate the AML. So does it generate the spec for you the specs, like, the Rspec specs for you, or do you still have to write those separately?

Svyatoslav Kryukov [00:25:35]:
So yeah. In in my case, I wrote a gem that called Skooma. And that gem adds, like, 3 or 4, helper methods to Rspec or minitests, to your request tests. So, to test your request against the the specification, all all, you need is to prepare the request, call it, and then, write something like assert the specification or or, it depends on on the, framework. But, like, it is ex expected to conform schema, the code of response that you are looking for. That's it. Like, one line. With that one line, you are get like you will test all the headers that you write in your documentation, in your specification, all the attributes, body attributes, like request, response, all that is just one line.

Svyatoslav Kryukov [00:26:44]:
So that's that's a great way to clean up your tests, I guess.

Charles Max Wood [00:26:49]:
Yeah. That sounds awesome. So then so then you just go and implement. Right? So then you're writing your your API through your controllers or I saw in your article you were using grape API, which I may ask you about in a minute. But yeah.

Svyatoslav Kryukov [00:27:05]:
So That's a way. An example. Yeah.

Charles Max Wood [00:27:07]:
Yeah. Yeah. I I I love grape API, and I hate grape API. So, anyway, it's yeah. So so that that's pretty much it. So you're you're you've got your documentation then in YAML, and you've got your tests that run and things like that. So, I guess the other thing that I'm I'm wondering about here because there are some benefits to OpenAPI. Right? Yep.

Charles Max Wood [00:27:35]:
I'm pretty sure you can you know, if you have OpenAPI compliant documentation, then you can import it into Postman and things like that. And if you haven't tried to Postman, you should. It's it's a terrific tool. But I guess my question is, what about written documentation? Because to a certain degree, yeah, just having it pull up and say, you know, yeah, you're gonna send this kind of a request. You're gonna get this kind of a response. You're gonna see this kind of behavior, you know, on the other end. But sometimes you need a little bit more than that. So how how far does this get you as far as, like you said, the API being the product? How far does this get you as far as somebody like me coming along and going, okay, how do I talk to this app? And being able to get the information I need out of it without necessarily being able to read the YAML file or being able to see it?

Svyatoslav Kryukov [00:28:28]:
Sure. So, OpenAPI, allows you to extend itself, like, with special x keywords. So all of those, generators, like documentation gen generators, they come with those, special keywords that you can use to generate, like, special, pages and

Charles Max Wood [00:28:52]:
Okay.

Svyatoslav Kryukov [00:28:52]:
Use markdown to, explain everything you want. So, there is also idea that you can tag use tags to your, requests and also add a description to your tags. So for example, you come to users tag. And so like a big chunk of your documentation and you can put markdown there and just kinda explain everything about users you want. So, yeah, that's all available there.

Valentino Stoll [00:29:28]:
So I'm curious what your approach is for, like, you know, sample data. You know, that's definitely one of the, like, hardest problems I find with even doc documenting specs. Right? Like, is how do you fake the data in a way that is also, like, accurate to the usage? Right? Like, you can't just, like, sample production data all the time. And so, like, what what is your approach for that? And then maybe how does, like, the opening having it as a separate specification, how the how how does that help, you know, in that process?

Svyatoslav Kryukov [00:30:01]:
Right. So, to me personally, I was, interested in that at some point, but then it wasn't needed, on other, like, projects. So I'm not currently, you know, up to date here, but there are different ways. For example, there is an issue in Skooma to allow such, like, interface for, adding examples from the test data, like, providing that, and adding that to the, specification. I hopefully will come to to that issue, someday. So, another thing is that, like, what's the issue that you want to fix? If you want to fix the problem that your, example data might be out of sync with the, rules that you, described. There are, like, plenty of, tools to validate that because, OpenAPI, it's a common standard. There are, like, different languages and different tools.

Svyatoslav Kryukov [00:31:18]:
You are not scoped to Ruby only tools. So there is, like, a lot of tools for almost every idea and thing to to do. So, yeah, I I I don't remember the name for for that tool, but it's definitely there.

Valentino Stoll [00:31:39]:
Yeah. I mean, just as an example, I think of your, you know, original use case where you had the end date that was, like, to infinity. You know, like, how do you, like, how do you even model that from a fake data perspective? You know, how did you, in this case, like, document or, maybe not even document, but specify that, in the specification?

Svyatoslav Kryukov [00:31:59]:
So the specification allows you to use it depends on the version. Like, if if it's version, 3 point o, you you can, send that it's nullable, true. And if it's, like, more common, like the current version 3.1, you can use, like, array of types, I guess. That's something, that you can do. And, yeah, that's by the way, that's painful because, if you will write null, now without, like, not not as a string, that will be null, the data, not the string, which is painful. But, anyway, so yeah. And in that case, I don't think you can do anything but just using your plain, like English to to to to just describe what is happening because that's what documentation does. Probably you you can't read documentation that contains only examples.

Svyatoslav Kryukov [00:33:00]:
Right? That that's a strange documentation like rails guides. And there is just full list of you know you know there is a site with, like, something in 15 minutes or something like that, like different languages and all that. That's just one big chunk of example. Yeah. That's that's you can use that, but

Charles Max Wood [00:33:25]:
So when you're designing APIs, right, so let's say you you you're like, alright. You know, I need an API for my application, and I'm putting it together, and, you put it out for feedback from your coworkers or, you know, maybe customers or whoever. Right? What kind of feedback are you generally looking for and how do you prompt them to give that to you? Because I swear, like, half the time when I ask for any kind of feedback, like in a PR or something, it's just like, yep. That's good. Right? And so and and I and I want real feedback. Right? It's like, no. We we don't do it that way, or this would make this easier on me when I'm building some other thing. Right?

Valentino Stoll [00:34:11]:
Yeah. So

Svyatoslav Kryukov [00:34:13]:
I don't know. Like, that, feedback, it sounds like the feedback from people who not interested in, the result. You know? And I don't mean, like, in rude way. I mean, like, yeah, that that will be fine. I don't I don't really care because you will make it work. Right? I I do understand that you will do that. But in API, that's an interface that will be used by those people. So they kinda they want that to be easy for them.

Svyatoslav Kryukov [00:34:44]:
So maybe they already thought about some, edge cases in the UI or something like that. Again, the pagination is is a great example because, for example, they want to use, like, infinite scrolling, and they can use, like cursor pagination or they want to use, like, pages. And you did the cursor pagination, and it's obviously not that something that they can use. So yeah.

Charles Max Wood [00:35:08]:
Okay.

Valentino Stoll [00:35:09]:
Yeah. I'm I'm this makes me think, so I I'm in GraphQL a lot. That's what all of our clients use, and that it makes you think like of a oh, I I love it. But, but it makes you does make me think, like, you know, a lot of times, you'll have the front end people separate from the back end, and you'll have the same story as kind of working in parallel. Right? Like, where somebody will be working on the interface and somebody will be working on the back end stories. And you'll raise kind of, like, you know, to make sure that, you know, front end team can align with the back end, but also, like, that you're supporting everything that they need. And a lot of times, people will just, like, make, you know, fake wrappers of what they might expect to need, you know, in order to build whatever that they're building. You know, what what is your like, where does that, you know, specification aspect fit, in that kind of workflow where, you know, people need to use it right away and the specification gets molded kind of as it's getting worked on.

Svyatoslav Kryukov [00:36:15]:
Yeah. So the great thing about, OpenAPI is that you have mock servers, for example. So they can use them, and, you don't need to touch a keyboard for that. So they will have their mock data, and you don't need to, like, do that, yourself in in the back end code. Another thing is, that it's fine to, get back to the specification. It will happen, like, to all humans, as I said. So yeah. But the, probability, I think, is much, you know, less it's much less common to to, go back and fix something if you already thought about that, in the first place.

Charles Max Wood [00:37:17]:
So, Valentino brought up GraphQL, and I have not talked to anybody about OpenAPI for a long time. And I haven't really looked at Swagger or OpenAPI for a while. Does this work on systems like GraphQL, or is it only like REST systems?

Svyatoslav Kryukov [00:37:35]:
So right now, it's only REST systems. And it's it's even hard to implement, like, describe, something like RPC because that's just one endpoint. And, just what open API looks like, that doesn't work with with such cases. Mhmm. There is a new version, like the version 4.0, Moonwalk, I guess, it's it's it's called. So in that version, they do might like, they try to support, such cases when you have one endpoint and a lot of different, like, actions. So I don't think that GraphQL, is, like, interesting for for them, because it already has a schema and all of that. But, yeah, those cases with, when when you use just one, endpoint and a lot of stuff happening there because of, like, I don't know, like, different headers or break ramps, That's what what they try to, fix in the new version.

Charles Max Wood [00:38:46]:
So one other thing that I think would be good to cover for folks is we've used the terms open API and Swagger interchangeably. You wanna explain what they are?

Svyatoslav Kryukov [00:38:58]:
I don't know, about you, but I didn't. Because that's different things. Actually,

Charles Max Wood [00:39:06]:
I swag I may have used them interchangeably.

Svyatoslav Kryukov [00:39:11]:
Yeah. So Swagger is a company that developed the, first draft, like, the first, I guess, couple versions of open API, the thing, and called it Swagger, at the time. And they, decided to, like, they were occurred by another company, I guess. I don't like, something bear. Sorry. I don't remember the name. But, anyway, it doesn't matter. So they just decided to make it open source, the whole specification.

Svyatoslav Kryukov [00:39:44]:
And Uh-huh. Then they renamed it to open API and made it public. I mean, like, open source. And Swagger, that name they decided to keep and name, their tools, with that name. So when you talk about Swagger right now, you probably refer to their tool in, like, Swagger UI, Swagger editor, and so on.

Charles Max Wood [00:40:11]:
Okay.

Valentino Stoll [00:40:15]:
So all of this, you know, API automation and schema documentation just makes me think of function calling, in the AI realm. Are you are you using this, kind of methodology to, like for code generation purposes or for, like, augmenting, you know, AI workflows and stuff like that?

Svyatoslav Kryukov [00:40:40]:
So, as I said, I I prefer to, write open API docs, manually. So, yeah, in that case, something like, Copilot, it it helps a lot to write them. Mhmm. So but regarding code generation, actually, there are generators, in the open API realm. It's not about AI, but, anyway, since we are talking about that, you can generate, client side SDKs, which will include validation, serialization, all the good stuff. You don't need to write that. And, like, there are different languages and versions. There is even version for Ruby.

Svyatoslav Kryukov [00:41:27]:
And they even have SDK generators for server code so you can generate your server. I I don't know of any Ruby gems for that, like Ruby generators for that. But still, if you if you want to generate JavaScript something, yeah, you can do that. So, yeah, I know if I answered your question. I I

Valentino Stoll [00:41:50]:
was just looking at your, Skooma JSON, stuff where it it validates the schema. And that's very much kind of like what function calling does, when you're working with something like OpenAI. Right.

Svyatoslav Kryukov [00:42:04]:
So

Valentino Stoll [00:42:04]:
I'm just curious if, like, you were you were using it maybe for that purpose, in in the Ruby side.

Svyatoslav Kryukov [00:42:09]:
No. No. No. I may

Valentino Stoll [00:42:11]:
I may try it out. I'll let you know how it goes.

Svyatoslav Kryukov [00:42:14]:
So JSON Skooma is another gem that, like, implements another standard that is used under the open API. So when you describe, different things in in OpenAPI, it might be like query parameters, body, whatever. You use you actually use a JSON schema. In version 3.0, it was like subset, superset of JSON schema, which was painful for everyone. So, with version 3.1, which is the current version of OpenAPI, they, first of all, they upgraded the version like for 5 major releases of JSON schema, which is, that's a different story. But, yeah, they they also made it, like, Zest standard. So you can use that. And, yeah, that's that's a great tool, actually, for validation.

Valentino Stoll [00:43:13]:
Yeah. It's funny. You can, you can pass schemas, to, you know, these large language models, and it it knows how to adhere to it even without, like, the function calling aspect, which is kind of interesting. Yeah. So I'm curious, like, now that you have, like, this documentation first, like, approach, like, how do people like it on your team? Like, is it is it like everybody's excited about it? Or is it like kind of a struggle to get people on? Are people still hesitant? Like, how is it working out?

Svyatoslav Kryukov [00:43:44]:
It depends. It depends. So for example, Vladimir Dimitri with Paul Polcan, he he has it, I guess. I I don't know. Like, writing something manually without DSL, he just but, you know, the the approach, it's good for small teams, if there are different, stacks. But if you work in a full stack team or something like that, that's overkill basically if you don't need to discuss those APIs. Or for example, Inertia. Js, you you can use that to just eliminate, the whole, API thing from from your application.

Svyatoslav Kryukov [00:44:25]:
Because I don't know if you know about the Neopcha, but, it's a JavaScript library plus, it has plugins for, for example, Rails and for different front end frameworks like React, Vue, Svelte. I love Venezer. Yeah. So, when you use that in your application, you just replace your view files with, whatever framework you decided to, work on. So for example, with React, and there is no API for that. So it it just, like, passing the whole, bucket of data, just renders that. So, yeah, you you can remove the whole API thing from your application. And, yeah, no need for, manual YAML writing.

Valentino Stoll [00:45:21]:
Yeah. I think it it even works kind

Charles Max Wood [00:45:23]:
of like in a

Valentino Stoll [00:45:23]:
SPA, style of, app too, which is interesting.

Charles Max Wood [00:45:29]:
So is there anything else that we should know about with open API and swagger and all that stuff?

Svyatoslav Kryukov [00:45:36]:
Yeah. I don't know. Like, if you use open API to document things, whatever you use like r swag or, scuma or whatever, Please dig deep into the tooling stuff that they have because it doesn't matter if you generate your documentation with Rspec, for example. You still can use all those tools to, for example, link your API documentation. And with OpenAPI, your, API, it becomes I know you can touch it. Right? That's a whole new experience because that's something real. And since it's real, you can lint it, you can use static analyzers on that. And you can, for example, you can use tools to catch, like some errors or, for example, OWSP problems with like security, all that.

Svyatoslav Kryukov [00:46:43]:
So, yeah, that that's really powerful idea. And please, please play with that. You can use Winters. You can force everyone to add descriptions to to Rspec using those tools because you can use, winter and add that to CI. And, yeah, it will blow up unless someone, did their work properly.

Charles Max Wood [00:47:06]:
Nice.

Valentino Stoll [00:47:07]:
It it sounds like what you're saying. There's there's no excuse for poor API documentation.

Svyatoslav Kryukov [00:47:13]:
Yeah. Yep. Oh, but

Charles Max Wood [00:47:15]:
I like my excuses. They make me comfortable with being lazy.

Valentino Stoll [00:47:21]:
Do you do you create API documentation for, like, side projects and just one off things that you're trying out?

Svyatoslav Kryukov [00:47:31]:
That's such a painful question, actually, because all my side projects, they are more like gems. And that logical thing to do, like, why not document your gems first? Right? Like Right. No. No. My gems has next to 0 documentation. That's so painful you asked that.

Valentino Stoll [00:47:53]:
That

Svyatoslav Kryukov [00:47:53]:
that's so rude. I'm sorry. Like, we we almost we we look we're almost done with the podcast and you yeah.

Charles Max Wood [00:48:00]:
We never would have known.

Valentino Stoll [00:48:02]:
I to be to be honest, like, I I I'm curious about this question. Right? Because, like, you know, why don't you why don't we, like, have this creativity and, like, experimentation, like, with a documentation first thing? Like, what is, like, the barrier from us, like, thinking about our ideas in a specification way, versus, like, where we're trying you know, like

Svyatoslav Kryukov [00:48:26]:
Mhmm.

Valentino Stoll [00:48:26]:
I don't know. I it's a it's a question I think about a lot.

Svyatoslav Kryukov [00:48:30]:
That's all about, like, the the talk that I told about, from aerial Kaplan. It's all about that that you are, you can write that documentation upfront because you have to like, you are so energetic at that moment. You are, like, creating stuff and it's it's easy. You you want to, like, understand it yourself and you think I will I will, do that way or that way and I need to fix those such cases. And, you know, at that moment, that's just when you can do that after, like, after you did all work, it's just like describing, all that, and and it's it's the worst part.

Charles Max Wood [00:49:16]:
Well, it's funny because not just documentation, but in other areas. Right? I mean, I still see people that and and I've gotten out of the habit of writing tests. Right? Or writing good tests, or, you know, some of the other code hygiene things that I do on the front end, that I know I should do. Right. And so it really just comes down to, I mean, not even whether or not you believe it or believe it to be a good thing or worth your time. It's a matter of discipline, and and it seems like a lot of this stuff just comes down to discipline. Right? Are you committed to writing the best code you can? Are you committed to delivering the highest quality product you can? Right? I mean, obviously, as you approach perfect, it takes more and more effort to get it, you know, to get more quality out of it. But, you know, are you committed to putting out stuff that just, you know, ticks all the boxes on stuff that is maintainable.

Charles Max Wood [00:50:20]:
Right? Because we're not talking about, oh, you know, I'm gonna write this documentation so that I can pat myself on the back. I'm writing this documentation because I know that it'll make somebody else's life easier. Right? I know that it'll make it easier to maintain. I know that it'll do these things for me. And so it it really is down to discipline and whether or not you're willing to do the sometimes tricky stuff in order to make it work. But the thing that I found too is that the more I do those kinds of things, the better off I am because, my skill level goes up. Right? I can more easily tackle more difficult problems because I've done the discipline then to write to make sure that my documentation is up to date or to make sure that my tests run and pass and that I have decent test coverage or, you know, that I am breaking up my huge models or giant controllers or whatever other thing, right, that I know I should do. I'm doing it because it makes a difference later later on down the road.

Charles Max Wood [00:51:26]:
So, anyway, I'll get off my soapbox, but the the discipline questions, one thing that I like to hit is, you know what you're supposed to do. Are you doing it?

Svyatoslav Kryukov [00:51:37]:
The processes the the processes can help you also, like, linters. Yeah. Just just turn on the, linter that, like what it was. Like, the linter that tells you to write 5 lines of code with max for for a

Charles Max Wood [00:51:55]:
Oh, right. Well, I don't always agree with those, but the thing is is that you can like with RuboCop, you can make it whatever you want it to be. Right? So you can tell it, no. I'm okay with 10 line methods. Right? Or you can just turn the rule off if that's something, or maybe it just check it, check for egregious stuff. If it's 50 lines, then I have a problem. Right? I don't know. But but, yeah, getting into it, it's like, okay.

Charles Max Wood [00:52:24]:
And that's the other thing is is I think people get into the mindset of my documentation has to be perfect the first time or right? Or, you know, the the linting rules. The linting rules have to be exactly what I want. Sometimes you have to fuss with it a little bit in order to figure out. And it's not even to get what you want. It's to figure out what you want so that you can have it. Right? And so it's, you know, 5 lines of code and a method is way too restrictive. Right? I just I find myself frequently needing 8. Right? So I'm gonna bump it to 10.

Charles Max Wood [00:52:54]:
Right? Totally fine. Go to 10. Right? Not hurting anybody. But, you know, a lot of times, those are the other excuses that we use to not do the stuff that we know we ought to have in place.

Svyatoslav Kryukov [00:53:08]:
The cool stuff about, like, all those rules that you can, yeah, turn off of them, but that's an opt in action. You need to think about that. Why can I do that? It's like strong migrations gem that allows you to ignore all those rules. Like, you're trying to, like, break, add a new index, for example, to the table. And it yells at you like, hey, guy, that that will be, like, painful if there is too much data. But you know that it's like a 10 lines of, like 10 rows. So you can do that. So it's all about that, you know, thinking who could

Charles Max Wood [00:53:51]:
Yep.

Valentino Stoll [00:53:52]:
I don't wanna think. No. I think, I'm I'm curious, like, how, how all of this will pan out in the long run. And I it makes me think of, like, you know, things like, you know, Copilot or something like that where, you know, you're just documenting things, and then it just fills stuff out. And it'll it'll be interesting to see how those kinds of developers evolve over time. And and, hopefully, like, you know, the auto documentation test aspects of it just, like, happen. Mhmm. But but I don't think we're there any anywhere near term.

Valentino Stoll [00:54:32]:
But I do think about, like, you know, Gary Bernhardt's, like, original destroy all software stuff. And Mhmm. When I was getting into tests, you know, for the first time and just seeing that, like, workflow, you know, he's just wild. Like, oh, yeah. Let me open up a test so I can make sure that this thing works right. And, like, before he does anything, like, no code written. Right? Like, I was like, okay. I want it.

Valentino Stoll [00:54:54]:
I describe basically, it's documentation. Right? I describe how I want this thing to work, and then I go make sure that it works. Right? And that's definitely a very like, it's a shift in how, like, you're kind of taught, like, coding wise where it's like, alright. Just go try to do something. Right? And I think that's maybe why we have a hard time in our side projects, like, documenting things. It's like, we just wanna go try it. Right? And we just wanna, like, mess around with stuff. And maybe we need to, like, veer away from that, like, thinking and learn how to mess around with things in a more controlled way.

Svyatoslav Kryukov [00:55:30]:
Yeah. There was an another, wild idea. Like, I I think it's from Ben when when he was in in, SOD bots. So it was idea that he will just remove, all noncommitted code, like, once a for a while. When so when, he work on something, he, gains more information. He knows what he wants to do. And if it's not committed, then it's okay. He will just write it, again, and it will be better.

Svyatoslav Kryukov [00:56:01]:
Something like that. So, yeah, not another extreme idea. I I I Yeah. I know. One from Was

Valentino Stoll [00:56:08]:
it Toby Luke Luke from Shopify? He's notorious for doing that for just, like, nuking his entire, you know, stuff that hasn't made it and just rewriting it again. And there I forget what yeah. There was a there's a Kent Beck must do with stuff like that

Charles Max Wood [00:56:24]:
too. Yeah.

Valentino Stoll [00:56:25]:
Yeah. I forget what they called that. Yeah.

Charles Max Wood [00:56:29]:
I think it was red, green, and then there was something else. And it was basically you throw the code away and do it then.

Svyatoslav Kryukov [00:56:37]:
Throw the

Valentino Stoll [00:56:37]:
code away.

Charles Max Wood [00:56:38]:
And I can't remember what he called it. But yeah.

Valentino Stoll [00:56:40]:
I mean, I don't know how many times I've, like, gone in and done code and then had just, like, it disappear because I committed the wrong thing or, like, missed something or rebase. Right? And then they're like, whoops. I don't know where that went. And then I just, like, rewrote it, and it was good. So it can be good, but it's frustrating.

Charles Max Wood [00:57:00]:
Alright. Well, let's go ahead and get into the PICs. Oh, it's it's, it's TCR. It's test and commit and then revert or test and then commit or revert. And so if it's not good enough to commit, then you revert and do it again. Anyway, let's do picks. Let's let's, start wrapping up. Valentino, what are your picks?

Valentino Stoll [00:57:19]:
So as my recurring trend seems to be, I have a of AI picks here. One is called yudio.io. I yudio.com. Sorry. It's basically a really awesome, AI music generator, where you just give it a prompt and it generates, like, incredible songs. This is wild. But it also lets you, like, focus on either either just, like, the instrumental aspect or you can break it out, and I've been messing around with it. It's so much fun.

Valentino Stoll [00:57:52]:
My, other pick is, I came across I I've been playing with a lot lately, which, if you're not familiar, just lets you try out a bunch of different large language models that are are open source and available. And I came across, this, project called Lit GPT, which basically is a llama, but with, the ability to pretrain and fine tune and adds a bunch of those aspects of large language model development on top of it. And so I've been messing around. This is a lot of fun, and it makes it super easy to get started with all that stuff. So I recommend checking that out.

Charles Max Wood [00:58:34]:
Very cool. I'm trying to pull together some stuff. Maybe I shouldn't announce it before I have it ready. I'm trying to pull together some stuff to put together, an AI and Ruby summit and just bringing people who are working on all this stuff because it seems like there's a lot, and it's very, very interesting. So, anyway, I don't have dates or anything or even know who the speakers are, but, yeah, looking at that. My picks, I usually start out with a board game. And I'm just I'm not thinking of a board game I really wanna pick. So I'm I'm gonna pass on that.

Charles Max Wood [00:59:15]:
I am going to pick if you haven't read it yet, folks. Ayush, who's one of our other cohosts, he wrote the rails and hot wire codex. And I decided, you know, because sometimes I'm how do I put it? I guess, in the past, the way that I've learned things is just by kind of, I need this. I need it to do it, and so I'm gonna go find the way that it gets done. And he kind of walks you through the process of, of doing the things that you're, you know, that you're looking at there. And so, I'm about a quarter of the way through the book at this point. And so far, he's walked you through building your own authentication. He's walked you through, setting up, turbo native for Android and iOS.

Charles Max Wood [01:00:07]:
He's walked you through a bunch of other stuff, you know, some fundamentals on stimulus and stuff. And, yeah, so a lot of it I knew, but, some of it I wasn't as familiar with. And it's been really, really fascinating to work through it. And at the same time, you know, kind of get a better handle on some of the things where I had kind of muddled my way through and now go, oh, okay. This is this is how this works. And so this is the way that I ought to be doing it. And sometimes I disagree with his approach, but it's been really fascinating to get through it. So I'm gonna pick the rails and hot wire codex.

Charles Max Wood [01:00:43]:
It's about a $100. It's an ebook that he put together. And then I got back into The Walking Dead. So several years ago, I worship watched the first, I don't know, 5 seasons. And, then I quit watching it, and they've put out, like, 11 seasons, and they have, like, 5 spin offs. And I was like, I really liked that show, so I've been rewatching it. So I'm gonna pick The Walking Dead. And, yeah, I guess the other piece is is I've been kind of doing a rewrite of top end devs, basically with a lot of the stuff I've been picking up out of the rails and Hotwire codecs.

Charles Max Wood [01:01:26]:
And I have to say, I am very, very happy with tailwind and tailwind UI, so I'm gonna pick those 2. Alright. Svyat, what are your picks?

Svyatoslav Kryukov [01:01:38]:
So yeah. Sure. I I really struggle, maintaining focus while reading books. So my first pick will be Speechify, which is a AI based, text to speech application, and that helps me read more. It highlighted text, supports, like, importing ebooks and all that. So, that's basically my go to app for reading right now. Another pick, will be, Kagi search. I hope I I, pronounce that right.

Svyatoslav Kryukov [01:02:18]:
It's a paid search engine, which is, by itself, already interesting and unusual. So the their idea is that they are privacy first. And there is also a feature that I want to highlight, which is they have integration with different AI models, like Chargept or Google's Gemini. And all of that for 25 bucks a month versus $20, in chat GPT, for example. So, they don't offer all the features from ChatGPT. Like, you can't use, for example, for images. But still, that's a great, thing to use. I also love that I don't need to go, from, the search engine because that's my go to site, basically.

Svyatoslav Kryukov [01:03:13]:
So yeah. And $20 plus $5, for search engine. Right now.

Charles Max Wood [01:03:20]:
Alright. Well, if people wanna follow-up and, find you on the Internet and ask you questions or, you know, give you feedback on what we talked about on on your verbal API?

Valentino Stoll [01:03:31]:
Sure.

Charles Max Wood [01:03:31]:
Where where where do they find you?

Svyatoslav Kryukov [01:03:33]:
Yeah. You can find me in on Twitter or x, whatever you work you use. So it's s krukoff, _dev, and I'm s krukoff on, GitHub.

Charles Max Wood [01:03:49]:
Alright. Well, we'll have all that in the show notes. Thanks for coming. This was awesome.

Svyatoslav Kryukov [01:03:52]:
Cool. Thanks for having me.

Charles Max Wood [01:03:54]:
It it just it makes me wanna go play with open API and the swagger tools and see what I can do with it now. So