Lesson Weekend

The digital agency we're working for just got big news. A university library has asked us to build an API of literary and movie quotes that other applications can use. The front-end developers on our team will build the website while the back-end developers have to stop playing ping pong and get to work on building the API.

We'll start by creating our first endpoint, keeping it simple for now. Before we continue, we'll need to add a database with rake db:create.

First, we need some routes:

config/routes.rb
Rails.application.routes.draw do
  resources :quotes
end

Next, we'll add some code to our quotes_controller:

controllers/quotes_controller.rb
class QuotesController < ApplicationController

  def index
    @quotes = {"quotation": "The secret of getting ahead is getting started."}
    json_response(@quotes)
  end

  private
  def json_response(object, status = :ok)
    render json: object, status: status
  end
end

Let's examine the code. We're passing a simple JSON object into an instance variable. (The quote is from Mark Twain.) Then we call a custom json_response() method on the instance variable. We could pass our quotation directly into our json_response() method, but we'll be using instance variables soon anyway.

Now let's take a look at our json_response() method. render() is a Rails method that takes :json as an option. (We've used render() in our vanilla Rails apps to render html.) It will automatically call to_json() on the object that it's passed in. Our object is already JSON, but in future lessons we'll be rendering database objects as JSON instead. We also pass in the API call's status code. Note that the argument for status is status = :ok. This just means that :ok is the default value of status. Now we only need to pass an argument into the method if the status is something other than :ok.

HTTP Statuses

The render() method also accepts a status option. Here we're passing in a status of :ok, which means the call was successful. We could also choose to pass in the integer 200 instead of :ok because 200 is the universal HTTP status code for a successful call.

Now we can test this call using Postman. Run $ rails s and pass in the URL http://localhost:3000/quotes. Postman should return {"quotation": "The secret of getting ahead is getting started."} with a 200 ok status.

Try passing in another status code (such as 401) into the index route and then check Postman again. The status is now listed as 401 Unauthorized even though the call was successful.

In our application, we'll always want to make sure we pass the correct HTTP status codes to the end user making the API call. This can help the user diagnose what went wrong — or right — about their calls. We'll go over this further in future lessons.

Take a look at the Rails docs regarding render, specifically the section "2.2.12 Options for render," which explains the options that can be passed into render as well as the HTTP status codes and Ruby symbols for various response classes.

Our API isn't very useful so far. We only have one hard-coded quote. In future lessons, we'll refactor our code, hook the controllers up to models, build out controller routes, and add testing for our API.

Lesson 3 of 19
Last updated August 7, 2022