Apoorv Kansal Apoorv Kansal - 1 month ago 10
reST (reStructuredText) Question

REST API dealing with nested relationships

So I am building a REST api and I am struggling to handle deeply nested relationships. Here is an example of some of the resources I have:

Profiles - a user can be a client or vendor profile.

Events - client profiles can create events (eg. social events which have attributes such as time, name, location etc.)

Tasks - Under an event, a client profile will create a "tasks" that need to be completed by a vendor profile for THAT event (eg. A task could be providing Photography service for an event).

Job requests - Once the client profile has created tasks for their event, they can send out job requests for each task to vendor profiles (here the vendor profile has the opportunity to accept the job request and become HIRED/ASSOCIATED to the the task).

I am also using a token based authentication scheme.

My question: How should I go about designing the URLs? I have contemplated over producing flat URLs likes

/tasks/
and
/profiles/
but realised that my design is very hierarchical and would require more context. For instance, a client profile might want to see the job-request they sent out so the URL might look:


/profiles/id/events/id/tasks/id/job-requests/id


I am incredibly reluctant to maintain such a complex tree oriented URL. Which one would be better suited for my scenario and why?

On top of choosing between flat or tree oriented URLS, I need to provide different forms of data for the same resource. For instance, a client might want to access their created task and therefore should have FULL ACCESS to all attributes of that task whereas once a vendor is associated to a task (after accepting a job-request), they can only see some attributes of the task. In this scenario, it can be seen that some form of permission level is required and hence more context needs to be provided? If this is the case, how should I go about providing more context? I have considered two options:


  1. Stick with the tree oriented URLs which would result in these 2 urls:
    /profiles/id/events/id/tasks/id
    (client profile accessing their created task for an event)
    /profiles/id/job-requests/id
    (vendor profile accessing a client profile's task where they have been hired/associated.)

  2. Stick to flat urls (
    /tasks/id/
    ) for both the client profile and vendor profile, however once they provide their unique authentication token, I can map it to their profile and provide the necessary and allowed data to them automatically.



As a side note: You might be wondering why I put client and vendor profiles under

/profiles/


It's because both of these profiles have very similar data attributes and a user of the system might have multiple profiles (eg. Person A has a client AND vendor profile and are able to switch between them).

Thanks :)

Answer

STRUCTURE

I suggest to use flat structure:

/tasks/
/profiles/
/events/

Because it will be possible to show events that are related different profiles and tasks that are related to different events. From frontend view there is a really small difference between /events?profile_id=<id> and /profile/<id>/events/. Nested structure of your application should be described on model level and in documentation.

PERMISSIONS

This question is not related to API endpoints structure. Lets say that user wants to reach event. Regardlessly to the endpoints structure - you need to check has user access to this event or not. So you have event instance and can check user access to model field profile if it is necessary.