Getting hands-on with RESTful web services

Podcast Transcript

Neal Ford:

Hello everyone and welcome to the Thoughtworks podcast. My name is Neal Ford, one of your regular co-hosts.

Rebecca Parsons:

And my name is Rebecca Parsons, another one of your regular co-hosts.

Neal Ford:

As many of you know, we have lots of authors here at Thoughtworks and today Rebecca and I are going to talk to one of those authors, so I will let him introduce himself.

Biharck Muniz Araujo :

Hello everyone, this is Biharck Muniz Araujo. I am an engineer Thoughtworks. First of all, thank you so much Rebecca, Neal for having me here. It's an honor record this podcast with you guys. Currently I am based in Belo Horizonte office in state of Minas Gerais, Brazil and algorithms and software engineering have been my passion for the past 16 years. By the way, I do love to solve complex puzzles and mathematics problems.

Neal Ford:

All right, well let's talk about the complex puzzle that you solved recently when you wrote a book. So what's the title of this book and tell us what it's about, please.

Biharck Muniz Araujo :

Okay, yeah, this is a complex puzzle for sure. So the title of the book is Hands-On RESTful Web Services with TypeScript 3. So the main idea behind this is to show to developers how to design and develop a skill restful APIs for their applications. So the structure of this book is based on the hands on development of course, as its name says with TypeScript 3. A cool thing about this book is that there's an interesting content for the beginners, intermediate and expert level software developers, which means that no matter how experienced you are, I'm pretty sure that there is something there for developers to have fun. So as part of my academic life, I learned that when you are writing papers, books, briefings, I mean whatever the format you want to present, you should be careful writing something that is going to impress practical knowledge by going through practical use case. I mean real life problems.

Biharck Muniz Araujo :

So people usually don't want to learn how to use a methodology in language and algorithm, et cetera, by developing generic bakery house system. Right? They went to learn with a real industry problems using technologies that global companies are using to solve their own issues, helping them to innovate and move faster. Another thing I'd consider when I was writing this book was, I mean I kept asking a question to myself a couple of times. Like all right Biharck, how could you write a book about Typescript, explain how to use its features, put in practice, rest design, continuous integration, continuous delivery, security practice, deployment strategy, and at the same time show to the readers how to connect things together like this way they can go from scratch to the production environment with healthy API, which might be able to evolve since the zero. When they finished to ask that question for the first time, I was like, okay, it's time to give up because it's so complicated.

Neal Ford:

That's a pretty ambitious list for a book for sure.

Biharck Muniz Araujo :

I mean, putting myself in the reader's shoes, I want to read a book that shows to me the entire moving right, Not just a thriller. I went to see how to take advantage of the power of the language in the complex environment, not just a piece of information, like pieces of information sometimes you know it's more nice confusion than knowledge because they might be some specific or unique that become complicated to connect with other methodologists. Even more so if you are not an experienced developer. So I had this personal duty to do not do the same thing I used to complain. So this book is essentially divided in four sections. I mean this is interesting for guys want to I can explain like the first sections.

Neal Ford:

Yeah, absolutely.

Biharck Muniz Araujo :

Okay, so the first section is unraveling API design, which is, I tried to read this book starting from the basic concepts like shorten to reduction to restful API development, explaining restful concept in detail to help the readers to develop and run restful services. The main objective is to show comprehensive examples that transfer the concept to real scenarios and help them to understand the definitions in a straightforward way. Then moving on I show principles of design restful API, so prepare readers for getting familiar with best practice, like how to simplify operations, how to recognize endpoints, how to name. This is a hard one. How to name objects and CODIS in their organizations. Leaving the definitions behind and starting with concrete scenarios, the book shows how to design restful API is with open API in swagger, focuses on the core principles for creating web services, describing open API principles and implementation principles that can help just for design their web service to support feature chains and requirements. So moving on, section two I usually called developing restful web services, which is I decided first help readers to set up their environment, their development environment, because it's really annoying when you are ready to start with something and something goes wrong and you have no idea what's going on.

Biharck Muniz Araujo :

So or even worse when things come from like out of the blue. Having the environment in places is though one of the key elements I think for developers, I mean most developers get frustrated with configuration into so that's why I decided to explain how to configure everything before we get started. So once everything is in place, it's time to start building the first API, many folks on how to start the application. Then it focuses on the hard to define routes and how to handle logic that we run when a certain endpoint is called, handling requests and response, covering the steps to take after creating the first route. That is determining which properties you need while you're handling their requests that you receive and of course the importance to return meaningful response in order to change a bit date application states.

Biharck Muniz Araujo :

This book also covers how to format the API. I mean producing the content negotiation, output performance and how it is informed to explain stateless API conventions. And then it's time to have even more fun with the section three, which is enhancing the restful APIs and restful web services. So basically this section walks readers through the process to connect the APIs with database specifically with ODMs, object data manager, having them to set up a MongoDB database and connecting it with existing API, develop it through all the previous chapters. This section also covers security such as like authorization and authentication techniques. It describes also the importance of certain API with SSL and explains the way to validate data to avoid exposing sensitive information. Besides database insecurity, section of three also explains how to manage error handling and logging. I mean with other meaningful error messages, there was a really hard to debug. By the end of the section the reader would be able to create like their own CI/CG pipeline for their APIs pretty much for almost every application life cycle in deploying their application on the cloud.

Biharck Muniz Araujo :

Finally, section four is focusing on extending their capabilities off restful web services, which is basically developing the restful APIs with micro services strategy and flexible APIs with GraphQL, like some people even defining graph QL as restful 2.0, right? This section shows some difference and similarities between GraphQL and rest. So readers will learn how to add support for graph kale using the Apollo to their existing restful API with examples querying data, validating and executing queries.

Rebecca Parsons:

So it sounds like a lot of the book is focused on good design practices, good boundary setting, security, air handling. How much do you think your approaches to things like design or security were specific to the TypeScript tech stack or the other choices that you made with things like Mongo and such. And how much do you think it really is independent?

Biharck Muniz Araujo :

So I've tried to create like this script in a way that if the readers decide to change the language they could do that like easily. Of course I'm sort of taking advantage of some particular things with TypeScript that might help them to develop and the API in the script that I created, but talking about like designs, talking about the contract, talking about CI/CD security, like they are all common practice that could be applied to any language decide to use.

Neal Ford:

So to sort of summarize, the first part of the book is about unraveling API design. So that's very low level sort of rest stuff and an introduction to rest and make sure people are familiar with that. Section two is the sort of hello world developing restful services, but much more contextual. Three then enhances those and builds more real world things like data and those kinds of concerns like security. And then four talks about restful web services and a graph QL and some other cutting edge stuff. Is that a good summary of the sections of the book?

Biharck Muniz Araujo :

That's perfect. That's correct. Thank you for summarizing that.

Neal Ford:

Absolutely. So I'm interested in some of the technology choices you made here. So why did you choose TypeScript specifically? I know you that was a very specific choice on your part. So why was that?

Biharck Muniz Araujo :

Yeah, so I know that this might sound like a cliche, but that's no perfect language and that is going to serve like all of the problems and solve the world and save the world. I always like to say that to my students when I'm about to start a new class, I'm like, we should evaluate each scenario, each situation before making a decision about programming languages you know? After this disclaimer, it's been a way of, since Javascript is gaining traction, right. When I first started Javascript early 2000s I thought Javascript wasn't so cool. Maybe because I was like learning Java and at the moment and they used to be like a C developer. I don't know, but nowadays it's a little bit different like JavaScript is the most popular programming language and using the web. Beside to frequently visit some games are usually play, the apps you rely on, they would not exist if it weren't like for Java script but right everything that I'm talking right now it's about JavaScripts so why TypeScript for me?

Biharck Muniz Araujo :

There are a lot of opportunities with TypeScript such as like code is scalable with interface oriented development like types have the ability to enhance code equality and resting ability type like type safety has a feature to detect errors during the coding time which makes more efficient code and also we can debug like easily. Also types increase your agility when doing refactoring. It's better for the competitor to catch errors than to have things fail at runtime. I also think that like talking about contracts Types are one of the best forums for documentation and make sure they're following the contracts. You can take advantage of like dependency injection with TypeScript, which opens up a lot of cool opportunities for testing and perhaps controller visit API.

Biharck Muniz Araujo :

TypeScript also helps your trip limit, like of course solid designed patterns. There's also the ability to compile down to a version of Javascript that runs on all browsers. TypeScript has features that detects bugs as developers write scripts. What else? Refactoring with TypeScript is easier and faster than like if you're Javascript. TypeScript compiles reading Typescript, this is cool right? And it compares to JavaScript. I mean so TypeScript is a super set off of JavaScript. Typescript is JavaScript plus other features. So in the end of the day TypeScript is compared to JavaScript, it can be used for any Javascript code. Its popularity and its adoption are increasing dramatically since its first release. So TypeScript project, it's improving with every release including existing features such as like decorators. So I think that's why I decided to go with TypeScript.

Rebecca Parsons:

And I will resist the urge to start the religious war of static versus dynamic typing.

Neal Ford:

Yeah, so that's a classic trade off your list there, extols the virtues of Types without talking about any of the downsides, like the inability to create more generic solutions and other things like that. But certainly for a book about rest, it certainly makes sense to have something if you're going to be talking about contracts that can also implement those at the language level. So we won't question your choice too much and we might say that your enthusiasm for TypeScript slips into advocacy just a little bit.

Rebecca Parsons:

Although it is interesting the assertion as you alluded to Neal about the appropriateness of thinking in a Type way when thinking about contracts. I do think that's an idea that doesn't necessarily get as much credit as it deserves from people like me who really love dynamic types. So I do think that's something worth calling out as even if you don't explicitly use as a statically type language, if you are thinking about the design as a type, that will probably push you in a good direction when you think about the design of that contract.

Biharck Muniz Araujo :

That's absolutely true.

Neal Ford:

Yep, absolutely. And you also have the advantage that you spent several years writing a book about it. So you get the final say because you wrote a book about it. So let's talk about the other interesting part of the book beyond TypeScript, which is rest. Rest has been around for a while. So why write a book about rest now in 2019?

Biharck Muniz Araujo :

I think it's going to stay there for awhile. So I'll take part of the forward you wrote Neal. So by the way, thank you so much for writing that. I really appreciate that. So as you mention like rest certainly qualifies as a popular technology that continues to gain traction, just like all the other active software tools. So the through and approves evolve over time, which makes this book like a timely addition to the Corpus of books relating into the rest.

Biharck Muniz Araujo :

The main thing is that rest is just a way to express an API, as you guys mentioned, like rest has been around for many years and even so, so there are a lot of misunderstanding including like right now that this book's going to help such as, okay, rest is there for awhile, but we still see a lot of people with some misunderstanding around like HTTP status code or some patterns or how to describe their operations in verbs. So this book is going to briefly a little bit like rest and help them with some tips and tricks to help to better design their APIs. But besides that, like in the end of this book, I show like the readers how to evolve from the rest, the pure rest API, to a graph QL strategy. So I think it's like a trade off starting from, why does is most using right now and how to move forward with like rest to graph QL or any other technology.

Neal Ford:

Yeah, that's a good point. If you read a rest book from six or seven years ago, they're not going to talk about graph QL because it didn't exist at the time that the book is written. So even foundational technology like this, it helps to revisit them because the technology landscape continues to change and shift and new options keep coming up even for things that are well established paradigms. And like you said, we've been living with rest long enough that we now have patterns and best practices and it's less speculative about how to do this well and a much more of an established practice. So we touched on this a little bit about other technologies. So it definitely focuses on TypeScript 3 but you said earlier this is applicable to people using other technologies beyond just JavaScript, but even a Java or something in the .Net ecosystem or something like that?

Biharck Muniz Araujo :

Yes, that's absolutely true. So if you don't want to learn TypeScript, which I encourage you to learn, but if you don't want, you can take like the script I'm following into this book with any language you decide to learn how to design an API, how to create like a reliable security process, how to create like a CI/CD pipeline for this specific pipeline and how to make sure that you're building an API you won't hate in the future. So I think besides like TypeScript, this book is going to help you to more than just TypeScript.

Neal Ford:

So everyone on the call here has written a book now. So one of the things that always surprises me when I write a book are the interesting insights that you get that you never would have expected when you started that you have by the end of the book. So do you have any interesting insights or anecdotes that happened to you during the course of the writing of this book?

Biharck Muniz Araujo :

Wow. Oh, a lot of things that happened during the course of the writing, right? So the first one I managed to like write a meaningful book was one of the biggest concern that a lot of times put me in a bad situation. I mean I also learned that outlines change and change our lot. I created an outline for the editor. Then during the course I changed so many times and when I finished writing the book I was, "Oh, it's time to validate like the book with outline," and on those that I changed a lot of things again. So interested side is that the outline is just like a way to help you to drive you to the end of this challenge, but it's going to change a lot of times. Another interesting thing was how could I download what I'm thinking like my brain, the way that I'm used to usually write code so that readers can follow where I'm trying to explain. This is a really difficult part when you're writing a book which has like coding side.

Neal Ford:

Yeah, writing good clean code samples that don't have extra stuff and show exactly what you want is always a challenge when you write a book with a lot of coding in it, and making sure that all the code runs and it doesn't have syntax errors and all those things are always a challenge when you include technical artifacts like that. And yeah, you're right. Outlines always tend to drift and you try to keep them in line, but the books have a tendency to find their own way to become themselves. So what about stories that happened to you while you were doing the writing?

Biharck Muniz Araujo :

Yeah, long story. So just that was a challenge to people saying like, plant a tree, have a child, write a book. I'm from the countryside of my states so plant a tree was almost like having breakfast every day. So I have no idea how many trees I planted, like maybe a hundred don't know. Then I have a child like Liz is right now 11 months old. She's really good kid. So when I started writing this book, she was three months old. Sometimes and when they was ready she was with me with her pacifier look at me with her face like, "What are you doing daddy?" She has like one up that pacifier with a pet like giraffe and elephant and sometimes to decide to give to me, "Oh daddy, take some times and get my like best part to help you to clean your mind and move forward."

Biharck Muniz Araujo :

And this is the right time to say that weren't my wife Eileen and my daughter Liz. I wouldn't finish this book. They are amazing. And the reason that I get strong every day is because of them. So thank you Eileen and Liz for find the power of determination allowed. So other stories as I mentioned like outline, like up to now, I'm not sure which one is the hardest one. Like writing the consistent outline or writing a book. People that are listening to this podcast can picture a scene like, yay, I'm going to write a book. So you get a piece of paper and like a pencil and 30 days later you have the same piece of paper, the same pencil and the only difference that you have like this mug with the coffee and the paper and anything else. So it's really hard to get things for like your mind and put it in a consistent way. Like where you could create something which is interesting and connected. This is really difficult.

Neal Ford:

Yeah. Writing a book with a consistent unifying example throughout is also tough because you have to make sure it makes sense both in the examples and in the exposition, but also from the technology standpoint so that that makes the challenge even harder. So one last question for you. So one of our fellow colleagues said that he splits all writers into two camps, either the one time and done writer because after you've done it, it's so horrible, you never want to do it again. Or are you a serial writer? Do you think you'll do it again? So which one do you think you are?

Biharck Muniz Araujo :

Mmm, good question. So like right now I have a plan to write a book about a passion that I have which is algorithms. I sort of have a draft outline and I'm talking to editors about it, so we'll see.

Neal Ford:

Well I guess that answers the question. If you're shopping around for editors for a new book of some kind.

Biharck Muniz Araujo :

Yeah.

Neal Ford:

Well, thanks for joining us today. It's a really interesting book. I did the forward for it as you said, and it's a terrific book. It's a really good treatment and I think it's a timely topic and we'll even forgive you for using a TypeScript because it makes sense, as we said in this context. So thanks for writing a book and thanks for taking time to do the podcast with us.

Biharck Muniz Araujo :

Thank you guys.

Rebecca Parsons:

Yes. Thank you.

Neal Ford:

All right, thanks everyone, and we'll see you next time.

Zhamak Dehghani:

On the next episode of Thoughtworks podcast, we will be speaking with Andy Yates and learning about how to support citizen developers in your organization.