Because this API returns JSON data, you can easily customize the output by changing the way Rails converts a model to JSON. Rails first calls the as_json method on a model to convert it to a hash, which is then converted to a JSON string.

You can override the as_json method in the Post model to customize the data returned for each post. Open the file app/models/post.rb and add the as_json method, shown here, to force the method to show only each post’s id and title:

  class Post < ActiveRecord::Base
    --snip--

➊   def as_json(options={})
➋     super(only: [:id, :title])
    end

    --snip--
  end

Be sure to include the options parameter with a default value of {} ➊ because the original as_json includes it. You aren’t using the options parameter, but because you’re overriding an existing method, your definition must match the original. Your as_json method calls super, which invokes the original as_json method defined by Active Record, with the parameter only: [:id, :title] ➋.

With this method in place, your API should only return the id and title of each post. Use the curl command to verify the change:

$ curl http://localhost:3000/api/posts
[
  {"id": 1, "title": "First Post"},
  {"id": 2, "title": "Google Search"}
]

The as_json method supports several additional options. Instead of specifying fields to include with :only, you could exclude fields with the :except option. You can also include associated models with the :include option. For example, update the as_json method, as shown here, to exclude the user_id field and include the post’s associated user model:

def as_json(options={})
  super(except: [:user_id], include: :user)
end

The :methods option calls a list of methods and includes their return values in the output. For example, you can use this option to call the cached_comment_count method you added in Chapter 12:

def as_json(options={})
  super(except: [:user_id], include: :user,
    methods: :cached_comment_count)
end

This option will include the cached number of comments associated with this post in the output.

Overriding as_json certainly works, but depending on the level of customization required, this can get a bit messy. Fortunately, Rails provides a way to customize fully the JSON data returned by your API. Remove the as_json method from the Post model and let’s cover jbuilder.

Jbuilder is a domain-specific language for generating JSON output. The jbuilder gem is included by default in the Gemfile generated by the rails new command. Using jbuilder, you can create views for each of your API actions, just as you used ERB to create views for web actions.

As with your other views, you need to create a directory for your jbuilder views. The view directory must match the controller name. Enter the following commands to create a directory for API views and a subdirectory for the PostsController views:

$ mkdir app/views/api
$ mkdir app/views/api/posts

With these directories in place, you can create your first jbuilder view. Create a new file named app/views/api/posts/index.json.jbuilder and open it in your editor. Add this single line of code and save the file:

json.array! @posts

The json.array! method tells jbuilder to render the value of @posts as a JSON array. Use Curl to check the output of the index action:

$ curl http://localhost:3000/api/posts
[
  {
    "id": 1,
    "title": "First Post",
    "body": "Hello, World!",
    "url":null,
    "user_id":1,
    --snip--

The output is the same as when you started. Now let’s see about customizing this output.

The json.array! method also accepts a block. Inside the block, you can access each individual record in the array. You can then use the json.extract! method to include only certain fields from the post:

json.array! @posts do |post|
  json.extract! post, :id, :title, :body, :url
end

This example renders the id, title, body, and url fields from each post as JSON.

All of the usual view helpers are also available in jbuilder views. For example, you can include a URL for each post using the api_post_url helper method:

  json.array! @posts do |post|
    json.extract! post, :id, :title, :body, :url
➊   json.post_url api_post_url(post)
end

The output of method calls, such as api_post_url(post) ➊, are automatically converted to JSON format. The next example adds some data about the author of each post:

json.array! @posts do |post|
  json.extract! post, :id, :title, :body, :url
  json.post_url api_post_url(post)

  json.user do
    json.extract! post.user, :id, :name, :email
  end
end

Here, I’ve used the json.extract! method again to include only specific fields for each user. You don’t want to make the password_digest for users available through your public API.

First, add a field for the api_token string to the User model by generating a database migration:

$ bin/rails g migration add_api_token_to_users api_token:string

Remember to enter the bin/rake db:migrate command after generating this migration to update your database.

Now update the User model by opening app/models/user.rb in your editor and adding a validation for the api_token field and a before_validation call-back to generate the API token:

   class User < ActiveRecord::Base
     --snip--

➊    validates :api_token, presence: true, uniqueness: true

➋    before_validation :generate_api_token

     --snip--

First, you need to validate that the api_token is present and unique ➊. Because you’re using this value to authenticate, no two users can have the same api_token.

Next, you use a before_validation callback to call a method to generate the api_token if it doesn’t already exist ➋. Add the generate_api_token method at the bottom of the User model as shown here:

  class User < ActiveRecord::Base

    --snip--

    def generate_api_token
➊     return if api_token.present?

      loop do
➋       self.api_token = SecureRandom.hex
➌       break unless User.exists? api_token: api_token
      end
    end

  end

The generate_api_token method returns immediately if the api_token already has a value ➊. If a value is not present for the api_token, the method calls SecureRandom.hex inside an endless loop to generate a value ➋. The SecureRandom class uses the most secure random-number generator available on your computer to generate values. On Unix computers, it uses the /dev/urandom device; on Windows, it uses the Win32 Cryptographic API. The SecureRandom class also includes several methods for formatting random values. The hex method returns a random 32-character hexadecimal value. Finally, if a user with this api_token doesn’t exist, break out of the loop ➌.

Now open a Rails console and update the existing users:

➊ irb(main):001:0> user = User.first
    User Load (0.2ms) SELECT "users".* ...
  => #<User id: 1, ... api_token: nil>
➋ irb(main):002:0> user.save
     (0.1ms) begin transaction
    User Exists (0.2ms) SELECT 1 AS one FROM ...
    User Exists (0.1ms) SELECT 1 AS one FROM ...
    User Exists (0.1ms) SELECT 1 AS one FROM ...
    SQL (1.3ms) UPDATE "users" SET "api_token" ...
     (1.7ms)  commit transaction
  => true

Because the generate_api_token method is called automatically using a before_validation callback, you simply need to load the user into a variable ➊ and then save it to the database ➋ to update it. Do this for each of your users. If any user doesn’t have a value for api_token, it will be created.

Now update the user show view to display the api_token when a user views his or her own account. Update app/views/users/show.html.erb as shown here:

  <div class="page-header">
    <h1>User</h1>
  </div>

  <p class="lead"><%= @user.email %></p>

➊ <% if @user == current_user %>
    <p class="lead">API Token: <%= @user.api_token %></p>
  <% end %>

--snip--

Because API tokens are essentially passwords, you want to protect them by only showing them when the user being displayed is equal to the current_user ➊.

Now that all users have an API token, let’s put those tokens to use. The process of authenticating with a token is similar to the username and password authentication you already created. Because you may have more than one controller for your API, you should include the authentication method in ApplicationController, which is the parent class of all other controllers.

First, you need a method to authenticate using an api_token. Luckily, Rails has a built-in method called authenticate_or_request_with_http_token to handle the details for you. Open the file app/controllers/application_ controller.rb and add the following method to see how this works:

  class ApplicationController < ActionController::Base
    # Prevent CSRF attacks by raising an exception.
    # For APIs, you may want to use :null_session instead.
    protect_from_forgery with: :exception

    private

    def authenticate_token!
      authenticate_or_request_with_http_token do |token, options|
➊       @api_user = User.find_by(api_token: token)
      end
    end

    --snip--

This method is named authenticate_token! to match the authenticate_user! method you added in Chapter 9. The authenticate_or_request_with_http_token retrieves the token included in the request’s Authorization header and passes it to a block. Inside the block, you try to find a user in the database using the given token ➊. The find_by method returns a User object if a matching user is found, or nil otherwise. This value is assigned to the @api_user instance variable and returned from the block. If the block returns a false value, such as nil, the method knows that authentication failed and sends a 401 Unauthorized response to the client.

You wrote a helper method called current_user for accessing the authenticated user in Chapter 9. For API requests, the authenticated user is already assigned to the @api_user instance variable, so you can use this variable.

Your token-based authentication solution is ready to go now. Let’s try it out by adding the ability to create text posts through your API.

First, you need to add routes for text posts, so open config/routes.rb and add the text_posts resources inside the :api namespace:

Social::Application.routes.draw do
--snip--

  namespace :api do u
    resources :posts
    resources :text_posts
  end
end

Now you need a controller for text posts. Remember, it needs to be inside the api/ directory because the routes are in the :api namespace. Create a file named app/controllers/api/text_posts_controller.rb and add the following code:

  module Api
    class TextPostsController < ApplicationController
      respond_to :json
➊     before_action :authenticate_token!

    end
  end

This controller starts the same as the API posts controller. The TextPostsController class must be inside a module called Api. It also includes respond_to :json. The first change is the addition of before_action :authenticate_token! ➊. The controller calls the authenticate_token! method before each action.

You want to create text posts, so add the create method:

  module Api
    class TextPostsController < ApplicationController
      respond_to :json
      before_action :authenticate_token!
➊   def create
      @text_post = @api_user.text_posts.create(text_post_params)
      respond_with @text_post
    end
  end
end

The create method uses the @api_user instance variable set inside authenticate_token! to create a new text post ➊. You then use respond_with to send the new text post back to the client. Note that you don’t check to see whether the text post was actually created. The respond_with method automatically sends the appropriate error response if @text_post contains errors.

Because you also want to specify permitted parameter values, your final addition is a text_post_params method:

  module Api
    class TextPostsController < ApplicationController
      before_action :authenticate_token!

      respond_to :json

      def create
        @text_post = @api_user.text_posts.build(text_post_params)
        respond_with @text_post
      end

     private

➊    def text_post_params
       params.require(:text_post).permit(:title, :body)
     end
  end
end

The text_post_params method permits data for a :title and :body in a nested hash with the key :text_post ➊. This is the same as the text_post_params method in the controller for web requests.

Enter the curl command to try out the new API. Make sure to set the Content-Type header to application/json when you run the command, so Rails automatically parses the JSON data included with your request. Replace the word token with the actual api_token from one of your application’s users.

  $ curl -i 
       -d '{"text_post":{"title":"Test","body":"Hello"}}' 
       -H "Content-Type: application/json" 
       -H "Authorization: Token token" 
       http://localhost:3000/api/text_posts
1 HTTP/1.1 422 Unprocessable Entity
--snip--

Something went wrong: The status code 422 Unprocessable Entity ➊ means the data the client passed to the server is not valid. Check the server output in your terminal for more information.

  Started POST "/api/text_posts" for 127.0.0.1 at 2014-04-23 19:39:09 -0500
  Processing by Api::TextPostsController#create as */*
    Parameters: {"text_post"=>{"title"=>"Test", "body"=>"Hello"}}
➊ Can't verify CSRF token authenticity
  Completed 422 Unprocessable Entity in 1ms

--snip--

The data passed to the server is valid but didn’t include a CSRF token ➊. Remember, this token is not the same as the API token. The CSRF token is another unique token that is sent automatically when you submit form data in your application. Because you aren’t submitting a form, you have no way of knowing the correct CSRF token.

When you were updating the ApplicationController earlier, you may have noticed a helpful comment at the top of the class. Rails normally prevents CSRF attacks by raising an exception. This is great for a web application, but it won’t work for an API. Instead of raising an exception, you can prevent CSRF attacks by clearing out the user’s session data. Now any time the application receives data from a user that does not include the CSRF token, it clears the user’s session, effectively logging the user out of the application and preventing the attack.

Fortunately, rather than store authentication data in the session, API clients include the correct API token with each request. So API requests should work fine with a null session. Open app/controllers/application_controller.rb in your editor and make the following update:

  class ApplicationController < ActionController::Base
    # Prevent CSRF attacks by raising an exception.
    # For APIs, you may want to use :null_session instead.
➊   protect_from_forgery with: :null_session

    --snip--

In the protect_from_forgery method call ➊, change the value of the :with option to :null_session, and then try the same request again using curl:

  $ curl -i 
         -d '{"text_post":{"title":"Test","body":"Hello"}}' 
         -H "Content-Type: application/json" 
         -H "Authorization: Token token" 
         http://localhost:3000/api/text_posts
➊ HTTP/1.1 201 Created
  --snip--
➋ {
    "id":5,
    "title":"Test",
    "body":"Hello",
    "url":null,
    "user_id":1,
    "created_at":"2014-04-24T00:33:35.874Z",
    "updated_at":"2014-04-24T00:33:35.874Z"
  }

The status code is now 201 Created, which means success ➊. The HTTP headers are followed by a JSON representation of the new text post ➋. Because you didn’t create a jbuilder view for this action, the default JSON representation is used.

You can also open the posts index page in your browser, or issue an API request for all posts with the command curl http://localhost:3000/api/posts, to verify the text post was created successfully.