Using a single API route for all requests that us patterns.

[skydread1]

Context

In a classic backend API router, we would have different routes with different handlers for the different kind of actions to be performed.

Some of these routes might contain some authorisation middleware to ensure proper user permissions.

We do use this approach in our website still and the reitit router looks like this:

[["/posts"
  ["/all"          {:post ring-handler}]
  ["/post"         {:post ring-handler}]
  ["/new-post"     {:post ring-handler}]
  ["/removed-post" {:post ring-handler}]]
  ["/users"
  ["/logout"         {:get (auth/logout-handler client-root-path)}]
  ["/all"            {:post ring-handler}]
  ["/user"           {:post ring-handler}]
  ["/logged-in-user" {:post ring-handler}]
  ["/removed-user"   {:post ring-handler}]
  ["/new-role"
    ["/admin" {:post ring-handler}]
    ["/owner" {:post ring-handler}]]
    ["/revoke-role"
    ["/admin" {:post ring-handler}]]]
      ["/oauth/google/success" {:get  ring-handler :middleware [[auth/authentification-middleware client-root-path]]}]
 ["/*" {:get {:handler index-handler}}]]

Pullable API

Since, all the routes for pull pattern accept the same ring-handler , which route we chose does not matter.

The real API endpoints are actually highlighted as pure Clojure data in what we called the pullable-data:

(defn pullable-data
  "Path to be pulled with the pull-pattern.
   The pull-pattern `:with` option will provide the params to execute the function
   before pulling it."
  [db session]
  {:posts {:all          (fn [] (get-all-posts db))
           :post         (fn [post-id] (get-post db post-id))
           :new-post     (with-role session :editor
                           (fn [post] (add-post db post)))
           :removed-post (with-role session :editor
                           (fn [post-id user-id] (delete-post db post-id user-id)))}
   :users {:all          (with-role session :owner
                           (fn [] (get-all-users db)))
           :user         (fn [id] (get-user db id))
           :removed-user (with-role session :owner
                           (fn [id] (delete-user db id)))
           :auth         {:registered (fn [id email name picture] (register-user db id email name picture))
                          :logged     (fn [] (login-user db (:user-id session)))}
           :new-role     {:admin (with-role session :owner
                                   (fn [email] (grant-admin-role db email)))
                          :owner (with-role session :owner
                                   (fn [email] (grant-owner-role db email)))}
           :revoked-role {:admin (with-role session :owner
                                   (fn [email] (revoke-admin-role db email)))}}})

The advantages of using the operation/pullable-data as API routes are that:

• multiple endpoints can be accessed in one request
• these multiple endpoints can both have side effects to execute, it is not a problem
• multiple routes are still verified and one error in one route prevent all side effects
• same handler for all request
• the router route name does not matter because it is the same handler for all request

Caveat

We used to have reitit middlewares to validate user permissions before.
However, as we have seen above, since all routes use the same handler, we could just use a route without permissions restrictions to perform critical actions (such as deleting a post for instance).

This issue #219 has been fixed in the PR #220. The authorisation has been moved to the pullable-data as you can see with the different call to with-role.

This makes sense because, once again, the pullable-data is the real API of the SPA (aside from a few login related routes).

Proposition

I suggest we should just have a unique reitit route for all requests like so:

[["/all" {:post ring-handler}] ;; all requests with pull pattern as params
 ["/users/logout" {:get (auth/logout-handler client-root-path)}]
 ["/oauth/google/success" {:get        ring-handler
                                               :middleware [[auth/authentification-middleware client-root-path]]}]
 ["/*" {:get {:handler index-handler}}]]

Also, since the pull pattern allows us to perform multiple actions at once and fetch different information at once, choosing only one route would be misleading and hide some of the actions that would be performed.

For instance, in our evt.app/initialize re-frame event:

:http-xhrio {:method          :post
                   :uri             "/posts/all"
                   :params {:posts
                            {(list :all :with [])
                             [{:post/id '?
                               :post/page '?
                               :post/css-class '?
                               :post/creation-date '?
                               :post/last-edit-date '?
                               :post/author {:user/id '?
                                             :user/name '?}
                               :post/last-editor {:user/id '?
                                                  :user/name '?}
                               :post/md-content '?
                               :post/image-beside {:image/src '?
                                                   :image/src-dark '?
                                                   :image/alt '?}
                               :post/default-order '?}]}
                            :users
                            {:auth
                             {(list :logged :with [])
                              {:user/id '?
                               :user/email '?
                               :user/name '?
                               :user/picture '?
                               :user/roles [{:role/name '?
                                             :role/date-granted '?}]}}}}
                   :format          (edn-request-format {:keywords? true})
                   :response-format (edn-response-format {:keywords? true})
                   :on-success      [:fx.http/all-success]
                   :on-failure      [:fx.http/failure]}

We can see that this pattern does a few things:

• get all the posts
• get the logged-in user if any

However, the route name is "/posts/all" which does not reflect the user action.

That's why, I think just having a generic route and let the pattern be the descriptions of what is being performed.

In some way, the pull-pattern is the routes.

@robertluo what do you think?

[robertluo]

Ring requests are just maps, we could even use pull patterns to match them; thus we can remove retit from our dependencies.