UPDATE 2019: This post resulted from my frustration trying to figure out the right approach while writing Master Ruby Web APIs. I’ve chilled out since then, and published a post on my views of REST & Co. these days: REST in peace.
At all my previous jobs, I’ve worked with web APIs. Either as part of a web application or just on their own, acting as backends for mobile games played by millions of people. My problem was the war that’s raging in the web API community on how to do things.
So I decided to dig into it and read as much as I could about a variety of topics: the Internet, HTTP, Web Standards, versioning, resources and a lot of other stuff, including the dreadful REST.
I learned a sh*t load of stuff, things that nobody teaches you at the university and that you’re too busy learning when you have a job (or too lazy…). I had a much better understanding of the web API War.
This API War is happening between two camps, the pragmatic developers who build web APIs for a living in stressful/startup conditions and the dogmatic academic who also build web APIs for a living (I think) but also participate in the creation of web standards. Working on web standards makes you see things within a bigger picture and on a much longer term. Unfortunately, it also tends to take you further from the day-to-day developer lifestyle.
That’s why people always pick a side when they fight over how to build web APIs. Different visions, different goals. But that’s good, it pushes people to take their thinking further and put in question what they know.
I’m not even going to talk about websites but even they are not 100% compliant with the RESTful constraints (think cookies/sessions, for example, that go against the stateless constraint). Plus, websites are just web APIs that outputs HTML; your browser is a software last time I checked, even if it delegates understanding the semantics of the application to you, a smart human.
This introduction ended up longer than planned. Oops. Don’t expect me to tell you who is right by the way, no one knows! Instead, let’s talk about my book and what I’m trying to do with it.
What is it?
So Master Ruby Web APIs. A wonderful name. It’s supposed to teach you how to become a ‘master’ at building web APIs with Ruby. It doesn’t really say what your current level needs to be in order to read it (Can you imagine if I called it ‘From Newbie to Master: A lesson on web APIs, Ruby and the hidden API War’? Actually, it’s not that bad…).
Well, I want anyone to be able to pick up a copy and dive into it. Unfortunately, I don’t want you to fall asleep reading a 5,000 pages manuscript. So it will start with HTTP and Sinatra. A nice and simple combination to review the basics of how HTTP is supposed to be used. But I’m not just going to tell you to follow the HTTP RFC, no, no, no. There are some practices out there that go against HTTP/REST and that are pretty interesting! So we will cover them too.
This first API we will build won’t be RESTful. It will just be a basic HTTP API to dive into HTTP and the best practices to handle versioning, caching, error handling and so on. You will find the pragmatic stuff (it’s easy and it works!) and the dogmatic principles (“It’s the right way.”, or so they say). To be fair, there will also be all the stuff that lies in the middle and that everyone agrees on.
See, I’m not taking sides. I used to. I started on the pragmatic side because that’s the one you find a lot on Stack Overflow and in existing applications. Then I learned more about HTTP, REST, web standards and I switched to the dogmatic side. But I never really applied what I learned. So I decided to stop taking sides. I’m right in the middle and that’s why I think you will like what I’m writing. I will explain why one side prefers one solution and why the other side doesn’t think it’s such a great idea. Don’t worry, to show you that, I will actually build stuff.
Once we will have all the HTTP concepts under control and an overview of how to implement features in different ways, we will build a complete API with the new Rails 5 API module. Still, it won’t be RESTful. I guess it will be kinda-RESTful (trademark pending). We will take the good from both sides and try a few different things.
I’m not going to tell you which side to pick, I’m sure you’re smart enough to do that yourself. But to make a smart choice, you need to know both ways, right?
Anyway, then we will change or re-create our Rails API into something else. Something as REST compliant as possible. Using the latest technologies and hypermedia formats, we will see if we can really build something without any versioning that can adapt and evolve like a website. I can’t tell you yet if we will succeed, you will need to read the book for that. It’s going to be a fun ride, trust me! Or don’t, it’s still going to be fun even without you… :(
Why am I writing it?
I’m going to be super generic and say that “it’s the book I would have loved to have when I started”. Cheesy but true. I still remember my PHP teacher: all you will ever need are GET and POST, the rest is useless. Hmm, ‘kay.
I also want to push people to understand more about web standards and we need them. They are super important for web development but I feel like the most recent generations of developers skip them and have no interest in reading them. But we owe that to Tim Berners-Lee! He created the freaking World Wide Web and made it all free and open. Once again, web standards are super important. Without them, we wouldn’t have HTTP, HTML, CSS, Javascript… Every browser would be different (I mean even more than now) and you would have to write CSS code (or whatever it would be called without a standard) for each one of them! Can you imagine the pain?!
I use the term ‘web standard’ very generally to regroup RFCs, W3C recommendations, ECMA standards and the others. Not very academic, but much easier to read for you.
I’m also trying to open people to REST and building hypermedia APIs in a fun way. Most books about the subject tends to be… as interesting as reading RFCs! Try it out and you will know what I mean. Fun and interesting are my two goals for this book. Oh, you won’t find any academic writing, I don’t have the vocabulary or the patience for that. The way I’m writing it is that I picture you (yes, yes, you RIGHT THERE!) in my mind and try to think how to not bore you to death and make you fall asleep. Let’s hope it works!
Who is it for?
This book is for everyone who has ever worked on a web API or is planning to in the next 10 years. Also, even if it’s about writing Ruby code, it’s mainly about building web APIs so whatever your favorite language is, you will probably learn a few things.
Since we are starting by deconstructing what you know about API development and HTTP, we start pretty low. Beginners welcome! The level will quickly rise however, and I don’t have the word ‘master’ in the title just for fun (or marketing).
My goal is to teach you everything about web APIs!
It doesn’t matter if you think versioning should be in the URL or in the Accept header, the book will cover both and a bunch of others.
It doesn’t matter if the JSON API specification makes you think about XML and triggers your stomach to purge itself. I personally like it and we will talk about it, but we will also be using simple custom JSON documents.
My feeling is that beginners and intermediate developers are the perfect readers. People with more experience might already know what I will share in the book. Whatever you decide, you’ve been warned!
Interested?
Now that this article is written, I can go back to actually work on the book and have fun reading Fielding’s dissertation and the RFCs he authored with other smart people.
If you’ve read until here, that means you are interested and I thank you for your attention! You can subscribe to the newsletter for the book over there. By subscribing, you will get a better discount than the guy next to you who didn’t subscribe (shame on him)!
If you have the soul of a beta tester, let me know! I’m looking for some people to help me review the book so if you think you’ve got what it takes, shoot me an email at thibault(at)devblast.com. It’s a very fair agreement since you get the book for free and, you know, I get you for free. Everyone wins!
The book is expected to be released in the next two months so it’s not that far away! At least, that’s the plan if the word count doesn’t explode along the way…
Thanks for reading, I will be sharing more things about the book soon!
