resources

Psychic provides resourceful routing to encourage devs to think about their app in terms of resources. While the needs of an application will by highly diverse from app to app, they can all be boiled down to a collection of resources which will ultimately fill their databases and represent their user's state within the context of their application.

It is fundamentally essential to think this way, since you are already being forced to do it when you separate out your application's needs into a collection of tables. The idea here is to extend these resourceful representations of your data up into the routing layer as well.

For example, if you are making an application that allows users to sign up and create a blog, you may need a users table, a blogs table, a posts table, and a comments table. It would be nice if your application could cleanly reflect some of these resources:

import { PsychicRouter } from 'psychic'

export default (r: PsychicRouter) => {
  r.resources('blogs', (r) => {
    r.resources('posts')
  })
}

GET     /blogs                          Blogs#index
POST    /blogs                          Blogs#create
GET     /blogs/:id                      Blogs#show
PUT     /blogs/:id                      Blogs#update
PATCH   /blogs/:id                      Blogs#update
DELETE  /blogs/:id                      Blogs#destroy
GET     /blogs/:id/posts                Blogs/Posts#index
POST    /blogs/:id/posts                Blogs/Posts#create
GET     /blogs/:blogId/posts/:id        Blogs/Posts#show
PUT     /blogs/:blogId/posts/:id        Blogs/Posts#update
PATCH   /blogs/:blogId/posts/:id        Blogs/Posts#update
DELETE  /blogs/:blogId/posts/:id        Blogs/Posts#destroy

You can use resourceful routes, but restrict the routes to only a collection. This is dead-useful, since often you are building an application which does express some resourceful routing, but does not need certain routes. For example, you may have no need for the destroy or update methods. Below is an example of resourceful route limiting:

// conf/routes.ts

import { PsychicRouter } from 'psychic'

export default (r: PsychicRouter) => {
  r.resources('users', { only: ['create', 'index'] })
  // same as:
  r.resources('users', { except: ['show', 'update', 'destroy'] })
}

GET     /users  Users#index
POST    /users  Users#create

Additionally, use the resource method to do the same, but with a singularized route endpoint. This is generally done when you do not need to pass an id to identify the resource, such as when the resource will always belong to the authenticated user.

// conf/routes.ts

import { PsychicRouter } from 'psychic'

export default (r: PsychicRouter) => {
  r.resource('user')
}

GET    /user  Users#show
POST   /user  Users#create
PUT    /user  Users#update
PATCH  /user  Users#update
DELETE /user  Users#destroy

Both the resource and resources method enable nesting, enabling you to express child routes. By default, all child routes will be treated as members of the resource (meaning, they need to be reached by id).

r.resources('users', { only: ['show'] }, (r) => {
  r.get('edit')
})

GET     /users/:id       Users#show
GET     /users/:id/edit  Users#edit

If you do not wish for your nested endpoint to contain the id as part of its signature, you can use the collection method, like so:

GET     /users/:id   Users#show
GET     /users/edit  Users#edit

r.resources('users', { only: ['show'] }, (r) => {
  r.collection((r) => {
    r.get('edit')
  })
})