Reorganize file for EPUB export

Author: madeindjs

en/api_on_rails.adoc

@@ -1,6 +1,7 @@
 = API on Rails 5
 Alexandre Rousseau <contact@rousseau-alexandre.fr>
 v1.0, 2019-01-08
+:doctype: book
 :toc:
 :imagesdir: img
 :title-logo-image: image:logo.svg[]
@@ -13,46 +14,46 @@ v1.0, 2019-01-08
 :author: Alexandre Rousseau
 :description: Learn best practice to build an API using Ruby on Rails 5
 :front-cover-image: image:cover.svg[]
-:revdate: 2019-01-09
+:revdate: 2019-01-10
 
-include::./00_before.adoc[]
+include::chapter00-before.adoc[]
 
 <<<
 
-include::./01_introduction.adoc[]
+include::chapter01-introduction.adoc[]
 
 <<<
 
-include::./02_api.adoc[]
+include::chapter02-api.adoc[]
 
 <<<
 
-include::./03_presenting_users.adoc[]
+include::chapter03-presenting-users.adoc[]
 
 <<<
 
-include::./04_refactoring_tests.adoc[]
+include::chapter04-refactoring-tests.adoc[]
 
 <<<
 
-include::./05_athentification.adoc[]
+include::chapter05-athentification.adoc[]
 
 <<<
 
-include::./06_user_products.adoc[]
+include::chapter06-user-products.adoc[]
 
 <<<
 
-include::./07_improve_json.adoc[]
+include::chapter07-improve-json.adoc[]
 
 <<<
 
-include::./08_placing_orders.adoc[]
+include::chapter08-placing-orders.adoc[]
 
 <<<
 
-include::./09_improve_orders.adoc[]
+include::chapter09-improve-orders.adoc[]
 
 <<<
 
-include::./10_optimization.adoc[]
+include::chapter10-optimization.adoc[]

en/00_before.adoc renamed to en/chapter00-before.adoc

@@ -1,3 +1,6 @@
+[#chapter00-before]
+= Before
+
 == Foreword
 
 "API on Rails 5" is based on http://apionrails.icalialabs.com/book/["APIs on Rails: Building REST APIs with Rails"]. It was initially published in 2014 by https://twitter.com/kurenn[Abraham Kuri] under the licenses http://opensource.org/licenses/MIT[MIT] and http://people.freebsd.org/~phk/[Beerware].

en/01_introduction.adoc renamed to en/chapter01-introduction.adoc

@@ -1,4 +1,5 @@
-== Introduction
+[#chapter01-introduction]
+= Introduction
 
 Welcome to https://github.com/madeindjs/api_on_rails[APIs on Rails] a tutorial on steroids on how to build your next API with Rails. The goal of this book is to provide an answer on how to develop a RESTful API following the best practices out there, along with my own experience. By the time you are done with _API’s on Rails_ you should be able to build your own `API` and integrate it with any clients such as a web browser or your next mobile app. The code generated is built on top of Rails 4 which is the current version, for more information about this check out http://rubyonrails.org/. The most up-to-date version of the _API’s on Rails_ can be found on https://github.com/madeindjs/api_on_rails[APIs on Rails]; don’t forget to update your offline version if that is the case.
 
@@ -23,7 +24,7 @@ By the end or during the process (it really depends on your expertise), you will
 * http://codeschool.com/[CodeSchool]
 * http://jsonapi.org/format/[JSON API]
 
-=== Conventions on this book
+== Conventions on this book
 
 The conventions on this book are based on the ones from http://www.railstutorial.org/book/beginning#sec-conventions[Ruby on Rails Tutorial]. In this section I’ll mention some that may not be so clear.
 
@@ -43,22 +44,22 @@ I’ll be using some guidelines related to the language, what I mean by this is:
 
 If for any reason you encounter some errors when running a command, rather than trying to explain every possible outcome, I’ll will recommend you to `google it', which I don’t consider a bad practice or whatsoever. But if you feel like want to grab a beer or have troubles with the tutorial you can always mailto:[email protected][email me].
 
-=== Development environments
+== Development environments
 
 One of the most painful parts for almost every developer is setting everything up, but as long as you get it done, the next steps should be a piece of cake and well rewarded. So I will guide you to keep you motivated.
 
-==== Text editors and Terminal
+=== Text editors and Terminal
 
 There are many cases in which development environments may differ from computer to computer. That is not the case with text editors or IDE’s. I think for Rails development an IDE is way to much, but some other might find that the best way to go, so if that it’s your case I recommend you go with http://www.aptana.com/products/radrails[RadRails] or http://www.jetbrains.com/ruby/index.html[RubyMine], both are well supported and comes with many integrations out of the box.
 
 * *Text editor*: I personally use http://www.vim.org/[vim] as my default editor with https://github.com/carlhuda/janus[janus] which will add and handle many of the plugins you are probably going to use. In case you are not a _vim_ fan like me, there are a lot of other solutions such as http://www.sublimetext.com/[Sublime Text] which is a cross-platform easy to learn and customize (this is probably your best option), it is highly inspired by http://macromates.com/[TextMate] (only available for Mac OS). A third option is to use a more recent text editor from the guys at http://gitub.com[Github] called https://atom.io/[Atom], it’s a promising text editor made with Javascript, it is easy to extend and customize to meet your needs, give it a try. Any of the editors I present will do the job, so I’ll let you decide which one fits your eye.
 * *Terminal*: If you decided to go with http://icalialabs.github.io/kaishi/[kaishi] for setting the environment you will notice that it sets the default shell to `zsh`, which I highly recommend. For the terminal, I’m not a fan of the _Terminal_ app that comes out of the box if you are on Mac OS, so check out http://www.iterm2.com/#/section/home[iTerm2], which is a terminal replacement for Mac OS. If you are on Linux you probable have a nice terminal already, but the default should work just fine.
 
-==== Browsers
+=== Browsers
 
 When it comes to browsers I would say http://www.mozilla.org/en-US/firefox/new/[Firefox] immediately, but some other developers may say https://www.google.com/intl/en/chrome/browser/[Chrome] or even https://www.apple.com/safari/[Safari]. Any of those will help you build the application you want, they come with nice inspector not just for the DOM but for network analysis and many other features you might know already.
 
-==== Package manager
+=== Package manager
 
 * *Mac OS*: There are many options to manage how you install packages on your Mac, such as https://www.macports.org/[Mac Ports] or http://brew.sh/[Homebrew], both are good options but I would choose the last one, I’ve encountered less troubles when installing software and managing it. To install `brew` just run the command below:
 
@@ -69,14 +70,14 @@ $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/inst
 
 * *Linux*: You are all set!, it really does not matter if you are using `apt`, `pacman`, `yum` as long you feel comfortable with it and know how to install packages so you can keep moving forward.
 
-==== Git
+=== Git
 
 We will be using Git a lot, and you should use it too not just for the purpose of this tutorial but for every single project.
 
 * sous Mac OS: `$ brew install git`
 * sous Linux: `$ sudo apt-get install git`
 
-==== Ruby
+=== Ruby
 
 There are many ways in which you can install and manage ruby, and by now you should probably have some version installed if you are on Mac OS, to see which version you have, just type:
 
@@ -104,7 +105,7 @@ $ rvm install 2.5
 
 If everything went smooth, it is time to install the rest of the dependencies we will be using.
 
-===== Gems, Rails & Missing libraries
+==== Gems, Rails & Missing libraries
 
 First we update the gems on the whole system:
 
@@ -138,7 +139,7 @@ $ rails -v 5.2
 5.2.0
 ----
 
-===== Database
+==== Database
 
 I highly recommend you install http://www.postgresql.org/[Postgresql] to manage your databases, but for simplicity we’ll be using http://www.sqlite.org/[SQlite]. If you are using Mac OS you should be ready to go, in case you are on Linux, don’t worry we have you covered:
 
@@ -154,7 +155,7 @@ or
 $ sudo yum install libxslt-devel libxml2-devel libsqlite3-devel
 ----
 
-=== Initializing the project
+== Initializing the project
 
 Initializing a Rails application must be pretty straightforward for you, if that is not the case, here is a super quick tutorial.
 
@@ -173,15 +174,15 @@ $ rails new market_place_api --skip-test --api
 
 As you may guess, the commands above will generate the bare bones of your Rails application. The next step is to add some `gems` we’ll be using to build the api.
 
-==== Installing Pow or Prax
+=== Installing Pow or Prax
 
 You may ask yourself
 
 > Why in the hell would I want to install this type of package?
 
 and the answer is simple, we will be working with http://en.wikipedia.org/wiki/Subdomain[subdomains], and in this case using services like http://pow.cx/[Pow] or https://github.com/ysbaddaden/prax[Prax] help us achieve that very easily
 
-===== Installing Pow
+==== Installing Pow
 
 NOTE: Pow only works on Mac OS, but don’t worry there is an alternative which mimics the functionality on Linux.
 
@@ -208,7 +209,7 @@ $ ln -s ~/workspace/market_place_api
 
 Remember to change the user directory to the one matches yours. You can now access the application through http://market_place_api.dev/. Your application should be up a running by now.
 
-===== Installing Prax
+==== Installing Prax
 
 For linux users only, https://github.com/ysbaddaden/prax.cr[Prax] distribute some Debian/Ubuntu precompiled packages. You only have to download `.deb` and instal with `dpkg`.
 
@@ -237,7 +238,7 @@ NOTE: When using prax, you have to specify the port for the URL, in this case ht
 
 You should see the application up and running, see image bellow:
 
-=== Gemfile and Bundler
+== Gemfile and Bundler
 
 Once the Rails application is created, the next step is adding a simple but very powerful gem to serialize the resources we are going to expose on the api. The gem is called `active_model_serializers` which is an excellent choice to go when building this type of application. It is well maintained and the https://github.com/rails-api/active_model_serializers[documentation] is amazing.
 
@@ -298,7 +299,7 @@ $ bundle install
 
 After the command finish its execution, it is time to start tracking the project with Git.
 
-=== Versioning
+== Versioning
 
 Remember that Git helps you track and maintain history of your code. Keep in mind source code of the application is published on Github. You can follow the repository at https://github.com/madeindjs/api_on_rails[Github]. I’ll assume you have Git already configured and ready to use to start tracking the project. If that is not your case, follow these first-time setup steps:
 
@@ -375,6 +376,6 @@ $ git push -u origin master
 
 As we move forward with the tutorial, I’ll be using the practices I follow on my daily basis, this includes working with `branches`, `rebasing`, `squash` and some more. For now you don’t have to worry if some of these don’t sound familiar to you, I walk you through them in time.
 
-=== Conclusion
+== Conclusion
 
 It’s been a long way through this chapter, if you reach here let me congratulate you and be sure that from this point things will get better. So let’s get our hands dirty and start typing some code!

en/02_api.adoc renamed to en/chapter02-api.adoc

@@ -1,4 +1,5 @@
-== The API
+[#chapter02-api]
+= The API
 
 In this section I’ll outline the application. By now you should have the bare bones of the application. If you did not read it I recommend you to do it.
 
@@ -13,7 +14,7 @@ $ git checkout -b chapter1 b98a9a7a328017640482af95beebc1d6e612e0ac
 
 And as a quick recap, we really just update the `Gemfile` to add the `active_model_serializers` gem.
 
-=== Planning the application
+== Planning the application
 
 As we want to go simple with the application, it consists on five models. Don’t worry if you don’t fully understand what is going on, we will review and build each of these resources as we move on with the tutorial.
 
@@ -25,7 +26,7 @@ We are not going to build views for displaying or interacting with the API, so n
 
 By this point you must be asking yourself, all right but I need to explore or visualize the api we are going to be building, and that’s fair. Probably if you google something related to api exploring, an application called https://www.getpostman.com/[Postman] will pop. It is a great software but we won’t be using that anyway because we'll use cURL who allow anybody to reproduce request on any computer.
 
-=== Setting the API
+== Setting the API
 
 An API is defined by http://en.wikipedia.org/wiki/Application_programming_interface[wikipedia] as _an application programming interface (API) specifies how some software components should interact with each other._ In other words the way systems interact with each other through a common interface, in our case a web service built with JSON. There are other kinds of communication protocols like SOAP, but we are not covering that in here.
 
@@ -54,7 +55,7 @@ RESTful APIs must follow at least three simple guidelines:
 
 This might not be clear enough or may look like a lot of information to digest but as we move on with the tutorial, hopefully it’ll get a lot easier to understand.
 
-==== Routes, Constraints and Namespaces
+=== Routes, Constraints and Namespaces
 
 Before start typing any code, we prepare the code with git, the workflow we’ll be using a branch per chapter, upload it to Github and then merge it with master, so let’s get started open the terminal, `cd` to the `market_place_api` directory and type in the following:
 
@@ -166,7 +167,7 @@ $ git commit -m "Set the routes contraints for the api"
 
 All right take a deep breath, drink some water, and let’s get going.
 
-=== Api versioning
+== Api versioning
 
 At this point we should have a nice routes mapping using a subdomain for name spacing the requests, your `routes.rb` file should look like this:
 
@@ -368,7 +369,7 @@ Finished in 0.00294 seconds (files took 0.06292 seconds to load)
 2 examples, 0 failures
 ----
 
-=== Conclusion
+== Conclusion
 
 It’s been a long way, I know, but you made it, don’t give up this is just our small scaffolding for something big, so keep it up. In the meantime and I you feel curious there are some gems that handle this kind of configuration:
 

en/03_presenting_users.adoc renamed to en/chapter03-presenting-users.adoc

@@ -1,4 +1,5 @@
-== Presenting the users
+[#chapter03-presenting-users]
+= Presenting the users
 
 In the last chapter we manage to set up the bare bones for our application endpoints configuration. We even added versioning through headers. In a next chapter we will handle users authentication through authentication tokens as well as setting permissions to limit access for let’s say signed in users. In coming chapters we will relate `products` to users and give them the ability to place orders.
 
@@ -40,7 +41,7 @@ $ git checkout -b chapter3
 
 Just make sure you are on the `master` branch before checking out.
 
-=== User model
+== User model
 
 We need to first add the `devise` gem into the `Gemfile`
 
@@ -161,7 +162,7 @@ $ git add .
 $ git commit -m "Adds devise user model"
 ----
 
-=== First user tests
+== First user tests
 
 We will add some specs to make sure the `user` model responds to the `email`, `password` and `password_confirmation` attributes provided by devise, let’s add them. Also for convenience we will modify the `users` factory file to add the corresponding attributes.
 
@@ -212,7 +213,7 @@ $ git add .
 $ git commit -am 'Adds user firsts specs'
 ----
 
-=== Improving validation tests
+== Improving validation tests
 
 It is showtime people, we are building our first endpoint. We are just going to start building the `show` action for the user which is going to expose a `user` record in plain old JSON. We first need to generate the `users_controller`, add the corresponding tests and then build the actual code.
 
@@ -373,7 +374,7 @@ $ git add .
 $ git commit -m "Adds show action the users controller"
 ----
 
-==== Testing endpoints with CURL
+=== Testing endpoints with CURL
 
 So we finally have an endpoint to test. There are plenty of options to start playing with. The first that come to my mind is using http://curl.haxx.se/[cURL] because is built-in on almost any Linux distribution and of course on your Mac OSX. So let’s try it out:
 
@@ -422,7 +423,7 @@ $ git add .
 $ git commit -m "Updates application controller to prevent CSRF exception from being raised"
 ----
 
-==== Creating users
+=== Creating users
 
 Now that we have a better understanding on how to build endpoints and how they work, it’s time to add more abilities to the API. One of the most important is letting the users actually create a profile on our application. As usual we will write tests before implementing our code extending our testing suite.
 
@@ -546,7 +547,7 @@ $ git add .
 $ git commit -m "Adds the user create endpoint"
 ----
 
-==== Update users
+=== Update users
 
 The pattern for *updating* users is very similar as *creating* new ones. If you are an experienced Rails developer you may already know the differences between these two actions:
 
@@ -657,7 +658,7 @@ $ git add .
 $ git commit -m "Adds update action the users controller"
 ----
 
-==== Destroying users
+=== Destroying users
 
 So far we have built a bunch of actions on the users controller along with their tests but we have not ended yet. We are just missing one more which is the destroy action. So let’s do that:
 
@@ -728,6 +729,6 @@ $ git add .
 $ git commit -m "Adds destroy action to the users controller"
 ----
 
-=== Conclusion
+== Conclusion
 
 Oh you are here!, great job! I know it probably was a long way, but don’t give up you are doing it great. Make sure you are understanding every piece of code, things will get better, in next chapter we will refactor our tests to clean our code a bit and make it easy to extend the test suite more. So stay with me guys!

en/04_refactoring_tests.adoc renamed to en/chapter04-refactoring-tests.adoc

@@ -1,4 +1,5 @@
-== Refactoring tests
+[#chapter04-refactoring-tests]
+= Refactoring tests
 
 In previous chapter we manage to put together some `user` resources endpoints. If you skip it (or simple missed it) I highly recommend you take a look at it. It covers the first test specs and an introduction to JSON responses.
 
@@ -136,7 +137,7 @@ So let’s add a method for handling the JSON response. If you have been followi
 $ git checkout -b chapter4
 ----
 
-=== Refactoring the JSON response
+== Refactoring the JSON response
 
 Back to the `refactor`, we will add file under the `spec/support` directory. Currently we don’t have this directory. So let’s add it:
 
@@ -207,7 +208,7 @@ $ git add .
 $ git commit -m "Refactors the json parse method"
 ----
 
-=== Refactoring the format param
+== Refactoring the format param
 
 We want to remove the `format` param sent on every request and instead of that let’s handle the response we are expecting through headers. This is extremely easy just by adding one line to our `users_controller_spec.rb` file:
 
@@ -248,7 +249,7 @@ As always this is a good time to commit:
 $ git commit -am "Factorize format for unit tests"
 ----
 
-=== Refactor before actions
+== Refactor before actions
 
 I’m very happy with the code we got so far but we can still improve it a little bit. The first thing that comes to my mind is to group the three custom headers being added before each request:
 
@@ -351,6 +352,6 @@ $ git commit -am "Refactors test headers for each request"
 
 Remember you can review the code up to this point at the https://github.com/madeindjs/api_on_rails[Github repository].
 
-=== Conclusion
+== Conclusion
 
 Nice job on finishing this chapter. Although it was a short one it was a crucial step as this will help us write better and faster tests. On next chapter we will add the authentication mechanism so we’ll be using across the application as well as limiting the access for certain actions.