The Beginning

1.1.1. Who is this book for?

This book starts slowly enough for beginners to understand, before switching to more complex topics. The minimum requirement is having some programming background and being able to understand some basic Ruby code.

I believe any developer will have to work on a web API one day, and this experience will be much easier with the knowledge contained in this book. That’s not all. Most of the techniques we will discuss in this book also apply to regular web applications.

Basically, if you are a web developer, this book is for you. I can also assure you that you will learn new stuff.

1.1.2. Requirements

There are not too many requirements for Master Ruby Web APIs. You can actually follow the whole book without writing a line of code, but I would recommend following the flow and building the applications while reading the book.

To build them, you will need a Linux or Unix based system. I provide a lot of commands that can be run easily in a terminal on those platforms and that will make your life simpler.

If you are currently using Windows, I recommend setting up Virtual Box with the Ubuntu Linux distribution.

1.1.3. How is this book organized?

There are 3 modules in this book. Each module is a set of chapters focusing on a common topic. Here are the 3 modules with details for each one of them.

1.1.4. How To Read This Book

This book is meant to be read from start to finish. While you could probably cherry-pick some chapters in the modules, you will probably end up confused if you try to follow the code in a similar way.

Note that the best format to read this book on a computer, and build the applications, is the static HTML website. The chapters navigation is simplified, and you will be able to easily copy and paste the code. If you just want to read through, which is totally possible as long as you really try to understand the source code, the PDF/EPUB/MOBI formats will be perfect for you.

1.1.5. Code Blocks

There is a large amount of code in this book. Actually, more like a huge amount. I believe reading code is the best way to learn coding. Don’t worry though, every example comes with enough explanation to understand what’s happening.

Code blocks will look like this:

def code_block
  'This is a code block!'
end

I also use them for commands that are meant to be run in a terminal. I don’t prefix the lines with $ in order to make them easier to copy. You should have no problem differentiating the code blocks from the terminal command blocks.

touch my_new_file.rb

In some occasions, I had to reduce the length of the lines of code in order to fit them in the boxes used in the book. Here is an example:

# Does not fit in PDF version
def something
  response.headers['Location'] = "http://localhost:4567/users/#{user['first_name']}"
end

# Alternative
def something
  url = "http://localhost:4567/users/#{user['first_name']}"
  response.headers['Location'] = url
end

1.1.6. Errors, Bugs, Problems

While I did my best to avoid mistakes, be it in spelling or in the code, you might encounter some of those. If you do, I would really appreciate if you could send an email to bo@samurails.com with the details.

You can also check this GitHub repository and create an issue there.

1.2.1. The Origin

More than one hundred years ago, the only way people could communicate was through telegraph. Soon enough, the telephone and radio were invented. These media became the links that human beings needed to reveal their potential.

The Intergalactic Computer Network was a computer networking concept imagined in the early 1960s by J.C.R Licklider, who was working at the Pentagon’s ARPA (Advanced Research Projects Agency). It’s basically the same Internet we have today.

From this first concept, the first version of ARPANET (Advanced Research Projects Agency Network) was made. It expanded into a network of networks in the following years before becoming the Internet as we know it.

The fundamental challenge when creating ARPANET was to make computers communicate with each other. It’s quite funny when you think that this is pretty much the focus of this book, but on a completely different level. Thanks to all the progress we have made, we are not doing low-level communication anymore. Today it’s much easier - and thanks to standards, we can use awesome technologies like the HTTP protocol to communicate with pretty much anything that supports it, from home automation devices to smartphones, (without forgetting your computers, of course).

1.2.2. The Importance of Documentation (a.k.a Standards)

The Internet is not one technology. It is not a black box that magically runs Google, Facebook, and your blog.

The World Wide Web is not an objective thing. It’s a patchwork of technologies and a set of agreements. More importantly, it is a social construct made by humans for humans.

In making the Web, there are as many abstract discussions as there are practical implementations. That means people need a place to read and comment about how things should be because, let’s be honest, a collective output is stronger than any individual output. Today it seems normal to have public access to all the standards and specifications that make the Internet what it is today.

But 40 years ago, none of that existed. It all started in 1969 with S. Crocker, who created the first RFC (Request For Comments) notes. They were a way for him to share ideas in an informal way with other researchers.

Those RFCs ended up focusing more and more on protocol standards and, thanks to their public accessibility, they were used by engineers and teachers in their work.

Today, web standards are maintained by organizations like the IETF (Internet Engineering Task Force) or the W3C (World Wide Web consortium) which publish them as recommendations. The impact of these standards is tremendous.

Not only do they provide optimal solutions for us to implement, but they also make it easier to create things! By adhering to those standards, your products will require less work and, for example, be better indexed. It also provides ways to help everyone, including blind people and people with poor eyesight, access the information from any device.

Standards give us accessibility and stability.

1.2.3. Documentation

We’ve seen before how important documentation has helped the Word Wide Web rise to the top. Nowadays, documentation is written by pretty much every developer. Showing how to use a library or a tool is mandatory if you’re looking for people to actually use your stuff.

We can mention Google’s and AWS’s documentation as examples of corporate documentation. I’m sure you’ve also written documentation before, so there shouldn’t be anything new here.

However, there are also more significant groups like the W3C (World Wide Web Consortium) or the IETF that take care of writing another kind of documentation. We have mentioned them before, but I’m obviously talking about web standards. In other words, this is not the standard documentation you write about code or tools, but rather a theoretical approach trying to create the best possible solutions for specific problems. Their creation can span years to allow time for feedback and improvements, and they end up being the “best way to do something” according to the community, the corporations, and the organization drafting them.

You don’t actually need web standards to create stuff for the web, but they make everything simpler. Think about CSS and the custom browser properties you have to use sometimes. What if you had to create three or four stylesheets, one for each browser you support? Luckily, browsers follow standards, which basically make your life much easier.

Following works pretty well for developing websites/web applications, but web APIs are kind of lagging behind. Most people today just create new fiat standards for every project, re-inventing the wheel every time. This also means they need to write a new set of documentation to cover everything about the web API functionalities. Using standards would save some precious time by removing the need to write walls of text to explain how things work, since this wall of text would already exist elsewhere (and presumably, already be understood by the wider community). You would still have to describe your application semantics, but this part could actually be addressed by upgrading to a hypermedia API with embedded documentation. We will learn more about this very soon.

The goal behind the creation of web standards is the long term growth of the World Wide Web (a.k.a WWW).

For now, let’s have a quick overview of how standards work and how to use them.

1.2.4. The Web Standards Organizations

There are a few organizations responsible for creating and maintaining the web standards of the World Wide Web.

The ones we are interested in as software engineers are the W3C, the IETF, and Ecma International. If you love standards, you can also take a look at the ISO, the ANSI and the Unicode Consortium, but we won’t be covering them here.

1.2.5. The Different Types of “Standards”

There are different types of standards depending on whom they are targeted at and available for. There are no official names for these different types, and are provided here more to give you an idea of the different categories of standards.

{
  "businessCard": {
    "firstName": "John",
    "lastName": "Doe",
    "url": "http://example.com"
  }
}

{
  "bCard": {
    "fName": "John",
    "lName": "Doe",
    "website": "http://example.com"
  }
}

{
  "@type": "http://schema.org/Person",
  "@context": {
    "givenName": "http://schema.org/givenName",
    "familyName": "http://schema.org/familyName",
    "homepage": {
      "@id": "http://schema.org/url",
      "@type": "@id"
    }
  },
  "givenName": "John",
  "familyName": "Doe",
  "homepage": "http://example.com"
}