Building a RESTful API in a Rails Application_part 2 (end)

4.2.2 ProjectsController

1. class ApiProjectsController < BaseApiController
2.   before_filter :find_project, only: [:show, :update]
3.   before_filter only: :create do
4.     unless @json.has_key?('project') && @json['project'].responds_to?(:[]) && @json['project']['name']
5.       render nothing: true, status: :bad_request
6.     end
7.   end
8.   before_filter only: :update do
9.     unless @json.has_key?('project')
10.       render nothing: true, status: :bad_request
11.     end
12.   end
13.   before_filter only: :create do
14.     @project = Project.find_by_name(@json['project']['name'])
15.   end
16.   def index
17.     render json: Project.where('owner_id = ?', @user.id)
18.   end
19.   def show
20.     render json: @project
21.   end
22.   def create
23.     if @project.present?
24.       render nothing: true, status: :conflict
25.     else
26.       @project = Project.new
27.       @project.assign_attributes(@json['project']
28.       if @project.save
29.         render json: @project
30.       else
31.          render nothing: true, status: :bad_request
32.       end
33.     end
34.   end
35.   def update
36.     @project.assign_attributes(@json['project'])
37.     if @project.save
38.         render json: @project
39.     else
40.         render nothing: true, status: :bad_request
41.     end
42.   end
43.  private
44.    def find_project
45.      @project = Project.find_by_name(params[:name])
46.      render nothing: true, status: :not_found unless @project.present? && @project.user == @user
47.    end
48.  end

The todos controller will look similar, even having to find a project in order to fulfill the RESTfulness requirement (one uniquely identifiable resource per endpoint).

4.2.2.1 Defensive Programming

Defensive programming is a software design principle that dictates that a piece of software should be designed to continue functioning in unforeseen circumstances. Because your API will be exposed to third-party developers, allowing them to submit arbitrary inputs, it is important to apply this practice in API design.

This is why has_key? is used above rather than simple existence checking. If @json['project'] came in as false, or null, a simple existence check would return false, even though we can not say with any degree of accuracy that no JSON request body will ever have a false node at a depth of one.

The more significant defensive choice was the inclusion of responds_to?(:[]). This is due to the fact that, if the request body were say {"project": "noteIAmNotAnObject"}, @json['project']['name'] would result in a server error. In the spirit of defensive programming, when building APIs, ask yourself, "what is the least expected, most random, or most malicious input a user can submit?" Then write code to handle it.

4.2.2.2 HTTP Status Codes

While it is tempting to simply return 200 (OK), 404 (Not Found), and 500 (Internal Server Error), HTTP status codes — very much like HTTP verbs — have well-defined meanings. For the benefit of other developers, use status codes that make sense. For example, if we have a uniqueness constraint on Project name, we should return a conflict status on creation attempt for name clashes to let the developers understand where they went wrong.

The exception to the rule is when an item exists but the API user does not have the right access privileges to act on it. While it might be tempting to return a 403 (Forbidden), this in and of itself provides an attacker with information about the existence of the item. Instead, return a 404 if the user cannot access the record, no matter what the reason.

4.2.2.3 Code DRY?

While the above does achieve the desired result, it is far from DRY. There are repeated JSON validations and a duplicate database read, once for read only on update, and once for update rejection on a non existing item for create. Additionally, any nested route, such as /api/v1/projects/:name/todos will require the same find methods so as to uniquely identify the correct resource.

5 A better way

First, we'll extract functionality common to all API endpoints into the BaseApiController.

1. def validate_json(condition)
2.   unless condition
3.     render nothing: true, status: :bad_request
4.   end
5. end
6. 
   
7. def update_values(ivar, attributes)
8.   instance_variable_get(ivar).assign_attributes(attributes)
9.   if instance_variable_get(ivar).save
10.     render nothing: true, status: :ok
11.   else
12.     render nothing: true, status: :bad_request
13.   end
14. end
15. 
    
16. def check_existence(ivar, object, finder)
17.   instance_variable_set(ivar, instance_eval(object+"."+finder))
18. end

This turns the create and update methods into calls to update_values, while the Project JSON validations call validate_json:

1. before_filter only: :create do |c|
2.   meth = c.method(:validate_json) 
3.   meth.call (@json.has_key?('project') && @json['project'].responds_to?(:[]) && @json['project']['name'])
4. end
5. before_filter only: :update do |c|
6.   meth = c.method(:validate_json)
7.   meth.call (@json.has_key?('project'))
8. end
9. before_filter only: :create do |c|
10.   meth = c.method(:check_existence)
11.   meth.call(@project, "Project", "find_by_name(@json['project']['name'])"
12. end
13. def create
14.   if @project.present?
15.     render nothing: true, status: :conflict
16.   else
17.     @project = Project.new
18.      update_values :@project, @json['project']
19.   end
20. end

The other, possibly more significant improvement is introducing a multi-tiered inheritance hierarchy into your controllers. A good way to break this out is based on route nesting. Todos are nested within Projects; therefore, any Todo will need to find a Project.

1. class ApiProjectRouteController < BaseApiController
2.   private
3.     def find_project
4.       @project = Project.find_by_name(params[:name])
5.       render nothing: true, status: :not_found unless @project.present? && @project.user == @user
6.     end
7.     def find_todo
8.       @todo = #...
9.     end
10.     #other finders also go here.
11. end      

ApiProjectsController now needs to inherit from ApiProjectRouteController rather then BaseApiController.

1.  class ApiProjectsController < ApiProjectRouteController
2.    #...
3.  end
4.  class ApiTodosController < ApiProjectRouteController
5.    #...
6.  end

6 Custom behavior

Unfortunately, APIs do not exist in a vacuum. The system will have its own set of predefined behaviors, and on occasion, despite the best of intentions it will be necessary to expose behavior through the API that is not available otherwise, or may even clash with the application's existing behavior. A specific, fairly common example would be the relaxing of validations.

For the sake of clarity, let us walk through an example. Let's assume that our system's Project model has a priority column that is required.

1. class Project < ActiveRecord::Base
2.   has_many :todos
3.   belongs_to :user
4.   validates :priority, presence: :true
5.   validates :name, presence: :true
6. end

Now let us assume that a major customer would like to integrate an in-house solution that allows Project Managers to bulk create Project entries without priority, as priorities have not yet been decided. However, the regular UI users should not gain these increased privileges. How could this be achieved? In short, we need the model to be aware of the request source, and apply one set of validations in case the request came from the API, and another otherwise.

The first thing to do, is to add this concept at the controller level. Adding a method to the BaseApiController:

1. before_filter :indicate_source
2. def indicate_source
3.   @api = true
4. end

The second thing to do is to allow the model to validate conditionally.

1. class Project < ActiveRecord::Base
2.   after_initialize :set_ivars
3.   has_many :todos
4.   belongs_to :user
5.   validates :priority, presence: :true, if: lambda{ |model| model.instance_variable_get(:@strict_priority_validation) }
6.   validates :name, presence: :true
7.   private
8.     def set_ivars
9.       @strict_priority_validation = true
10.     end
11. end

Now every time a model is instantiated it will set its validations to be strict, and apply the priority validation if strictness is true.

The final piece of the puzzle is sharing state between the controller and the model to override model level instance variables. To do this, we can define a PORO (Plain Old Ruby Object):

1. class ProjectValidationPicker
2.     def pick_a_validation(project, api=false)
3.         if api
4.            project.instance_variable_set(:@strict_priority_validation, false)
5.         else
6.           project.instance_variable_set(:@strict_priority_validation, true)
7.         end
8.     end
9.  end

And for the final piece of the puzzle, this object needs to be used on update/create. Handily, we already have a function on BaseApiController to do just that. Lets change this method to pull in a validation picker if it exists and to set the api appropriately.

1. def update_values(ivar, attributes)
2.   instance_variable_get(ivar).assign_attributes(attributes)
3.   validation_picker = check_validation_picker_existence(ivar)
4.   validation_picker.send(:new).pick_a_validation(instance_variable_get(ivar), @api) if validation_picker
5.   if instance_variable_get(ivar).save
6.     render nothing: true, status: :ok
7.   else
8.     render nothing: true, status: :bad_request
9.   end
10. end
11. def check_validation_picker_existence(ivar)
12.   Module.const_get (ivar.to_s[1..-1] + "_validation_picker").camelize rescue false
13. end

7 Debugging

Unfortunately, no code is ever perfect the first time it is written. While a detailed analysis of either of these tools is outside the scope of this article, it is worthy of note that both the Unix curl command, and the Google Apps Postman REST client allow crafting of custom requests to arbitrary endpoints.

8 Testing

With the code above, we have created a flexible, DRY, RESTful API. It allows us to have behavior that is unique to the API, while maintaining the same Database Models. But how can this be tested? Since the bulk of the lifting is done at the controller level, and since every request is a stateless transaction, request level specs are the most obvious fit. The simplest way to achieve this is controller tests, which do not differ significantly from the usual model for controller endpoint tests. Fundamentally, we craft JSON requests, and send them to the endpoints. A simple example might look something like this:

1. describe ApiProjectsController do
2.   before do
3.     @base_json = { api_token: @user.api_token }
4.     @project_json = {project: {priority: "4", name: "foo"}}
5.     @new_project_json = @base_json.merge(@project_json)
6.   end
7. 
   
8.   describe "actions" do
9.     describe "#create" do
10.        before do
11.         @request.env['RAW_POST_DATA'] = @new_project_json.to_json
12.          lambda do
13.           post :create
14.         end.should change(Project, :count).by(1)
15.       end
16. 
    
17.      it "returns ok" do
18.         expect(response.status).to eq(200)
19.         expect(Project.all.last.priority).to eq(@new_project_json[:priority])
20.         expect(Project.all.last.name).to eq(@new_project_json[:name])
21.       end
22.     end
23.   end
24. end

9 Other approaches and considerations

It is worth mentioning that the code outlined above represents only one possible approach to building a RESTful API in a Rails app. In fact it has made two, relatively significant tradeoffs.
The first, is that every request requires its own authentication. It is possible to avoid making this sacrifice using session cookies which Devise can also generate. I would argue that this complicates third party integration as it requires the developer to keep track of the session cookie, passing it in with every request instead of the api_token, as well as handling session expiration. In addition, it leaves the system exposed to attack, if the cookie origin is not scrutinized sufficiently, or even if the API consumer stands up to go to the restroom.
The second is that the in-house UI does not by default hit the same API endpoints. One solution would be to have Devise generate and expire a secondary, UI-only auth token, which does not trigger the API validation (maintains @api as false in BaseApiController), this may be stored in another column, or a different datastore entirely. Non-persistent in-memory datastores like Redis are particularly well suited to this application.
Finally it is worth noting that while this demo simply returns the entire resource, it is best practice to use a serializer to limit the subset of keys returned to what it is safe and/or necessary to expose.
10 Summary

We have covered how to build a REST api in an existing Rails application from the ground up, how to expose the endpoints, how to route to them, and how to allow custom behavior. We have touched on testing and debugging. While the example was fairly trivial, it is my hope that you can use it as a template for building scalable, reusable APIs.
Written by Abraham Polishchuk

If you found this post interesting, follow and support us.
Suggest for you:

Ruby Scripting for Software Testers

Python, Ruby, Shell - Scripting for Beginner

Professional Rails Code Along