How to structure routes for a Rest API

Question

I am confused on how to structure my routes. My application deals with timesheets and contains three models:

Employer
Employer id
Name and password

Employee
id
Employer id (FK)
Name and password

Timesheet
Employee id (FK)
Employer id(FK)
Timestamp

I want to select the timesheets for an employee based on the employee id, and be able to select the timesheets for all employees that work for a given employer using the employer id. In both cases, I would also like to be able to limit the timesheets I select to a specific week.

Here is what I have so far:

scope '/api' do
scope '/v1' do
  scope '/employees' do
    get '/' => 'api_employees#index'
    post '/' => 'api_employees#create'
      scope '/:id' do
        get '/' => 'api_employees#show'
        put '/' => 'api_employees#update'
          scope '/timesheets' do
            get '/' => 'api_timesheets#index'
            post '/' => 'api_timesheets#create'
              scope '/:date' do
                get '/' => 'api_timesheets#show'
                put '/' => 'api_timesheets#update'
              end
          end
      end
   end
end
end

I am confused whether I should make an entire new scope called "employers" that has employees and timesheets within it, or if I should put my existing scope inside an employer scope to avoid duplicates.

Answer 1

When I design routes, I think of a file system. For example, in your case, timesheets are files, and their IDs are the file names. Timesheets are held in the folders timesheets . If you are a linux/unix user, think of the root path as /usr/share , where the resources can only be read by anyone.

When I want to search for some timesheets, I add the search condition into query string, just like pressing CTRL + F in the file system.

When I want to restrict access to some timesheets, I put them in the user's home directory , which has the name of either /employers/:employer_id or /employees/:employee_id (the :xxx_id part can be omitted if you can identify them by login).

So the routes look like

scope 'api' do
scope 'v1' do

  resources :timesheets, only: [:index, :show]

  resources :employees, only: [:show, :update] do
    resources :timesheets, only: [:index, :create]
  end

  resources :employers, only: [:show, :update] do
    resources :timesheets, only: [:index]
  end

end
end

The "search by date" can be implemented in any index actions.