Routing

Helper Methods

JR has a couple of helper methods available to assist you with setting up routes.

jsonapi_resources

Like resources in ActionDispatch, jsonapi_resources provides resourceful routes mapping between HTTP verbs and URLs and controller actions. This will also setup mappings for relationship URLs for a resource’s relationships. For example:

Rails.application.routes.draw do
  jsonapi_resources :contacts
  jsonapi_resources :phone_numbers
end

gives the following routes

                     Prefix Verb      URI Pattern                                               Controller#Action
contact_relationships_phone_numbers GET       /contacts/:contact_id/relationships/phone-numbers(.:format)       contacts#show_relationship {:relationship=>"phone_numbers"}
                            POST      /contacts/:contact_id/relationships/phone-numbers(.:format)       contacts#create_relationship {:relationship=>"phone_numbers"}
                            DELETE    /contacts/:contact_id/relationships/phone-numbers/:keys(.:format) contacts#destroy_relationship {:relationship=>"phone_numbers"}
      contact_phone_numbers GET       /contacts/:contact_id/phone-numbers(.:format)             phone_numbers#get_related_resources {:relationship=>"phone_numbers", :source=>"contacts"}
                   contacts GET       /contacts(.:format)                                       contacts#index
                            POST      /contacts(.:format)                                       contacts#create
                    contact GET       /contacts/:id(.:format)                                   contacts#show
                            PATCH     /contacts/:id(.:format)                                   contacts#update
                            PUT       /contacts/:id(.:format)                                   contacts#update
                            DELETE    /contacts/:id(.:format)                                   contacts#destroy
 phone_number_relationships_contact GET       /phone-numbers/:phone_number_id/relationships/contact(.:format)   phone_numbers#show_relationship {:relationship=>"contact"}
                            PUT|PATCH /phone-numbers/:phone_number_id/relationships/contact(.:format)   phone_numbers#update_relationship {:relationship=>"contact"}
                            DELETE    /phone-numbers/:phone_number_id/relationships/contact(.:format)   phone_numbers#destroy_relationship {:relationship=>"contact"}
       phone_number_contact GET       /phone-numbers/:phone_number_id/contact(.:format)         contacts#get_related_resource {:relationship=>"contact", :source=>"phone_numbers"}
              phone_numbers GET       /phone-numbers(.:format)                                  phone_numbers#index
                            POST      /phone-numbers(.:format)                                  phone_numbers#create
               phone_number GET       /phone-numbers/:id(.:format)                              phone_numbers#show
                            PATCH     /phone-numbers/:id(.:format)                              phone_numbers#update
                            PUT       /phone-numbers/:id(.:format)                              phone_numbers#update
                            DELETE    /phone-numbers/:id(.:format)                              phone_numbers#destroy

Like resources, you may specify only: or except:, like jsonapi_resources :contacts, only: [:create].

jsonapi_resource

Like jsonapi_resources, but for resources you lookup without an id. Resources used with this route should be marked as singleton. See the Singlelton Resources section for more details.

Nested Routes

By default nested routes are created for getting related resources and manipulating relationships. You can control the nested routes by passing a block into jsonapi_resources or jsonapi_resource. An empty block will not create any nested routes. For example:

Rails.application.routes.draw do
  jsonapi_resources :contacts do
  end
end

gives routes that are only related to the primary resource, and none for its relationships:

  Prefix Verb   URI Pattern                  Controller#Action
contacts GET    /contacts(.:format)          contacts#index
         POST   /contacts(.:format)          contacts#create
 contact GET    /contacts/:id(.:format)      contacts#show
         PATCH  /contacts/:id(.:format)      contacts#update
         PUT    /contacts/:id(.:format)      contacts#update
         DELETE /contacts/:id(.:format)      contacts#destroy

To manually add in the nested routes you can use the jsonapi_links, jsonapi_related_resources and jsonapi_related_resource inside the block. Or, you can add the default set of nested routes using the jsonapi_relationships method. For example:

Rails.application.routes.draw do
  jsonapi_resources :contacts do
    jsonapi_relationships
  end
end

You can add relationship routes in with jsonapi_links, for example:

Rails.application.routes.draw do
  jsonapi_resources :contacts do
    jsonapi_links :phone_numbers
  end
end

Gives the following routes:

contact_relationships_phone_numbers GET    /contacts/:contact_id/relationships/phone-numbers(.:format)       contacts#show_relationship {:relationship=>"phone_numbers"}
                            POST   /contacts/:contact_id/relationships/phone-numbers(.:format)       contacts#create_relationship {:relationship=>"phone_numbers"}
                            DELETE /contacts/:contact_id/relationships/phone-numbers/:keys(.:format) contacts#destroy_relationship {:relationship=>"phone_numbers"}
                   contacts GET    /contacts(.:format)                                       contacts#index
                            POST   /contacts(.:format)                                       contacts#create
                    contact GET    /contacts/:id(.:format)                                   contacts#show
                            PATCH  /contacts/:id(.:format)                                   contacts#update
                            PUT    /contacts/:id(.:format)                                   contacts#update
                            DELETE /contacts/:id(.:format)                                   contacts#destroy

The new routes allow you to show, create and destroy the relationships between resources.

Creates a nested route to GET the related has_many resources. For example:

Rails.application.routes.draw do
  jsonapi_resources :contacts do
    jsonapi_related_resources :phone_numbers
  end
end

gives the following routes:

               Prefix Verb   URI Pattern                                   Controller#Action
contact_phone_numbers GET    /contacts/:contact_id/phone-numbers(.:format) phone_numbers#get_related_resources {:relationship=>"phone_numbers", :source=>"contacts"}
             contacts GET    /contacts(.:format)                           contacts#index
                      POST   /contacts(.:format)                           contacts#create
              contact GET    /contacts/:id(.:format)                       contacts#show
                      PATCH  /contacts/:id(.:format)                       contacts#update
                      PUT    /contacts/:id(.:format)                       contacts#update
                      DELETE /contacts/:id(.:format)                       contacts#destroy

A single additional route was created to allow you GET the phone numbers through the contact.

Like jsonapi_related_resources, but for has_one related resources.

Rails.application.routes.draw do
  jsonapi_resources :phone_numbers do
    jsonapi_related_resource :contact
  end
end

gives the following routes:

              Prefix Verb   URI Pattern                                       Controller#Action
phone_number_contact GET    /phone-numbers/:phone_number_id/contact(.:format) contacts#get_related_resource {:relationship=>"contact", :source=>"phone_numbers"}
       phone_numbers GET    /phone-numbers(.:format)                          phone_numbers#index
                     POST   /phone-numbers(.:format)                          phone_numbers#create
        phone_number GET    /phone-numbers/:id(.:format)                      phone_numbers#show
                     PATCH  /phone-numbers/:id(.:format)                      phone_numbers#update
                     PUT    /phone-numbers/:id(.:format)                      phone_numbers#update
                     DELETE /phone-numbers/:id(.:format)                      phone_numbers#destroy
Want to correct or improve this documentation? Edit this page on Github!