API Evangelist Conversation with Greg Dennis, Senior Software Engineer at Zeil

Hello, Kin Lane here, API Evangelist, just coming for one of my API Evangelist conversations where I talk to interesting folks who are doing interesting things from the world of APIs. Let’s not waste any time and dive right in, see what we got here. Hey there, who are you?

I’m Greg Dennis. My current role is with a startup called Zeil, that’s Z-E-I-L, in New Zealand. We’re reimagining what a job board can be by focusing primarily on creating an enjoyable candidate experience, by reducing job application rework and incorporating useful and functional AI to help candidates develop their careers. It’s jobs but smarter. My role is building direct integrations with the various HR systems that companies use to manage their people and active roles, in order to help reduce their workload when posting jobs.

Interesting. Sounds like a good one for you, it sounds like something that you can definitely contribute value to. But for everyone listening here, you and I have worked together at Postman. I helped bring you onto the Postman team, I guess technically I was your boss for a while, but Ben was your boss, but I was Ben’s boss. And so we worked on JSON Schema under the Postman Open Technologies brand. So I’m really keen on talking to you, I want to learn more about your view on APIs. And specifically, I’m very focused on HTTP APIs, so using the web, but you’re an expert in a different type of API. What can you do, though?

So my primary experience with APIs comes with libraries. As you mentioned, I’m heavily involved in JSON Schema, and as part of that involvement I build a set of open source libraries in .NET, so they’re published on NuGet.org. And the idea that an API, when I hear API I typically just think of a web API, but when I really think about what an API is, I realize that there are so many more different kinds of API. And one of the things that I’ve really focused on in developing my libraries is what that experience is when using the library. When I first started this journey, I was actually being introduced to the JSON syntax from the get-go, and at the time the premier JSON library in .NET was Newtonsoft.Json, and it has recently surpassed 5 billion downloads, which is just absolutely incredible. But it focused heavily on serialization, which is getting the JSON directly into a domain model that you might have for your business, kind of an object-oriented model. Whereas what I needed was a JSON DOM model where I could load in the JSON, parse it, mess with the JSON content, and then just spit out a new string. I didn’t need an object-oriented model, I just needed something to represent the JSON. And while it had that, I couldn’t figure out how to do it, so I built a new library to do that. And later on I learned what serialization is and I understood what Newtonsoft was trying to do, and you know what, it was trying to do, it makes a lot of sense now, but without that context it wasn’t very intuitive. So that was my first experience with a library API. I’ve got some other examples if you want to dive into those, but that’s pretty much what I think of when I think of APIs, is the library experience.

So your library, how long has it been around?

So starting that initial JSON DOM library, it was called Manatee.Json, I think I started that one almost a decade ago at this point. Over time it evolved to include serialization, JSON Schema, JSON Path, and a number of other things that it supported, and it was all bound up in one package. When .NET released its own JSON modeling system, System.Text.Json, it effectively replaced Newtonsoft as the de facto JSON system to be used in .NET. And so I thought that was a great opportunity to take my Manatee.Json and retire it and start fresh. I now have a project called JsonEverything, you can find the website at json-everything.net, and its various libraries are on NuGet, but all the functionality is split out to different libraries, so you can pick what you want and you don’t have to get all of the functionality, just take what you want.

Would you say that’s one of the benefits of a language API or a library API, that you can kind of really have that buffet? I mean, I guess you can do it with web APIs, but a lot of times you go to Stripe, you’ve got to take everything, and when you get the SDK, or some of these that aren’t too sophisticated when it comes to specific SDKs or language libraries. But do you think that kind of buffet is one benefit of a language library?

I think so. I think being able to take only the functionality that you need is much more beneficial than having to take all the functionality. And you mentioned Stripe, if I just want to interact with payments directly, I just want to be able to post a payment and get the payments that I’ve previously posted, I can’t download their SDK and only get those things. I download their SDK and I get access to their entire API. In order to access just those things, I would have to write the client code myself, a lesser experience.

So where did you learn to do this type of API programming, just using existing APIs, or did you pick it up?

It’s actually, I learned it by doing it, in building my libraries. I always functioned primarily on function. If it doesn’t work right, there’s no point in doing it. But beyond that, I wanted to make something that was intuitive and almost enjoyable to use. APIs, I think by their nature, are a creative work. When you’re designing an API, you want to make sure, I guess the gold standard for an API would be being able to use the API and know what it does without having to go look at the documentation. So I always tried to make the usability of my libraries such that they didn’t have to go look at the documentation. Of course I would still write documentation, but the goal was, make it so that they didn’t have to go look at the docs, if they could use the library just by downloading it, and the intelligence is there to see what methods are there and it all makes sense that way. That is the primary experience that you want.

Yeah, just making someone’s life a little bit easier, reducing friction, it’s just intuitive, speaks to a problem that they need. It’s the same as HTTP API design, but I think a lot of people get lost in API design, HTTP API design, just for the sake of design, and forget the fact that what you just described, as far as making someone’s life easier, this is about your consumer, this isn’t about being dogmatic about certain RESTful design principles or something. So I mean, do you have feedback loops with your users? How do you know what people are looking for and what you need to build into it, just based on your own, as an open source developer?

I would love to have feedback loops with my users. Unfortunately, I don’t. The only thing I can take from that is that people are finding it useful and intuitive enough that they don’t feel the need to come ask questions. I get an occasional question, and I’ll point them to the documentation, or if it’s not there, I’ll answer it as a question and then I’ll go add it to the docs. But then I can take that and tweak the user interface. It is basically a user interface. I can tweak the API to make that a little bit easier. But I always, I do think that simpler is better. If you’re building a web API and all you really need to do is expose access to the data that you’re hosting, maybe a CRUD API is really the best thing for you to do. I see a lot of library developers will try to be overly creative with how you go about interacting with their library, and there’s credibility in that, but I don’t think it helps usability, and for me usability is number one.

Yeah, simplicity matters when it comes to API design, whether libraries or HTTP web. I think I see a lot of folks going too far in the wrong direction. I feel like some event-driven, some GraphQL things, some things get pretty complex. But I’d like to, you’re neck deep in the JSON Schema community, which, I’m not a JSON Schema expert, I know enough to be dangerous, and I understand its value and ubiquity. So why is JSON Schema important to your work?

I really just became interested in JSON Schema because it was another thing that I could do with JSON. I was looking to expand the Manatee.Json library that I was working on, and JSON Schema had started up again after having been silent for a while, and it was like, this looks pretty neat. It was very heavily focused on validation of JSON data, and that’s basically what it is. It’s a JSON-based syntax, not really a syntax, it’s a JSON-based mechanism for working with and validating JSON data. That’s what it started as. Now people use it for all kinds of code generation, documentation generation, for so much that people have found use for it. So now the challenge that we are faced with is, how do we incorporate or adjust the specification to allow for all of those other use cases that people have found for it. Since Henry has moved on from JSON Schema into the OpenAPI world, Ben has been left as the primary author on the specification, doing a lot of work getting edits in and clarifications so that we can move into a new stable era for JSON Schema, where we’re focusing on stability between versions, which is a big complaint that we’ve had from users before. But yeah, we’ve got a lot of PRs in place and in progress, and I’ve got a bunch of stuff that I still need to change, and hopefully we’ll have something out early next year.

Nice. Well, thank you for your service on that, because JSON Schema was just so critical, and OpenAPI, AsyncAPI, all the specs have a lot of kind of drama and challenges keeping all the people in alignment to move forward. I’ve herded a lot of those cats for a while and I’m taking a break from doing that, so I’m very thankful that you stepped up and are continuing holding the torch, it’s super critical. But when it comes, based on everything JSON Schema, what keeps Greg coming back every day and doing this, especially on the side now? So you hired me at Postman to work on JSON Schema full time, and that was great.

I really did enjoy it, but I found that my passion for the project diminished. It was a passion project initially, something that I did on the side, and then it became my job. And as so many people have found, I’ve seen a lot of woodworking YouTubers have said, you know, this is my passion, I’m going to make it my job on YouTube, and then eventually kind of burn out on it. And I was starting to experience that stuff as well. So I think in the end, Postman pulling back their sponsorship of the individuals behind JSON Schema ended up being actually a really good thing for me, because I took some time off, I found a job, and I found that the passion that I had before, with editing and writing the specification and helping the community understand what we’re trying to do and work with it. And now that it’s something that I do when I want to do it, I find myself actually wanting to do it more.

Nice, that makes sense. And that again makes me very happy, because I was really worried about the specs as things were disbanded. So it’s good to hear that there’s still that energy and there’s still that community and will to move it forward. I appreciate you coming by today, Greg, and sharing with me. It’s been great having a conversation with you.

Absolutely, it’s been wonderful being here, thanks for having me.

All right, I appreciate it. Yeah, definitely stoked that Greg and others are able to continue contributing, because JSON Schema, I’m a big fan and supporter of OpenAPI, but for me JSON Schema is 10, 100x the importance of OpenAPI. I mean, OpenAPI uses JSON Schema in multiple ways, it’s critical. So it’s a spec we need to keep moving forward. All right, well, until next time folks, appreciate it.