-2

I started working on a app that will receive a "route" as json. That is the "route" itself will passed as a string to the server enclosed in a json string. I want to use a RESTful standard way of writing routes to keep things more easily debuggable later. However, as follows by example:

contact            'get all contacts
contact/:id        'get the contact by id

Ugly areas:

contact/:id/jobs            'get the contact and all jobs assigned to contact
contact/:id/jobs/filter     'get the contact and all jobs assigned to contact, 
                            'where those jobs meet a certain criteria (filter)

Now I could avoid overly verbose routes on "jobs" by having CRUD routes on "/jobs", which I will. But if I wanted limit returned "jobs" to a specific contact as in the above, is there a way to respresent that query without making up new conventions?

code_monk
  • 9,451
  • 2
  • 42
  • 41
mardubbles
  • 129
  • 6
  • You could have `/jobs?contactId=` that filters by the contact – Jacob Mulquin Apr 15 '22 at 02:09
  • True @JacobMulquin, if I wanted to do a regular URI type statement. How to write that as a "route" though? Unless you are saying I should treat "routes" of having additional GET params? I could do it that way. – mardubbles Apr 15 '22 at 02:15
  • 1
    This answer has some good insight: https://stackoverflow.com/a/33946754/1427345 – Jacob Mulquin Apr 15 '22 at 02:17
  • 1
    Its a good reference (the SO link you provided) reading it now. Appreciate it @JacobMulquin – mardubbles Apr 15 '22 at 02:19
  • Does this answer your question? [How to design RESTful search/filtering?](https://stackoverflow.com/questions/5020704/how-to-design-restful-search-filtering) – TylerH Apr 15 '22 at 14:18

3 Answers3

1

As far as RESTful architecture goes, practically speaking, what you have is fine. A more strictly RESTful pattern might look like this:

/jobs?contact_id=73284
/jobs?contact_id=73284&completed=1

where 73284 is the unique ID of your contact, and completed=1 signals a filter.

It's useful to understand strict RESTful principals, but in practice impossible to be 100% compliant.

In general, the pattern is:

METHOD:/resource/represention?any=query&string=you&want=here

or

METHOD:/resource?any=query&string=you&want=here

where METHOD is GET,PUT,POST,PATCH, or DELETE. resource is a class of things (think table name), representation is a particular thing (think table row), and query parameters are like what you put in WHERE clauses in SQL.

code_monk
  • 9,451
  • 2
  • 42
  • 41
  • I see where you are coming from on using the URI as a means for the server side api to handle. But literally in this application, the server will receive the route via AJAX as a route string. So it won't be processing GETs other than the "bundle" it receives. – mardubbles Apr 15 '22 at 02:38
  • Nonetheless your answer (+1) gives me insight on the limits of REST. – mardubbles Apr 15 '22 at 02:39
  • I think you're on the right track. Don't over-think it – code_monk Apr 15 '22 at 02:41
1

in my opinion, try use query, restful mostly means meaningful for me

contact/:id/jobs=>contact/:id?populate=jobs // if you want a contact with jobs, that means you still want a contact, just some additional info

contact/:id/jobs/filter=>contact/:id?populate=jobs&jobs[xx]=xx filter also means additional restrict

/jobs?contact_id=xx this shall mean you want job list, with some additional restrict

Josh Lin
  • 2,397
  • 11
  • 21
  • I thought about this (+1) wanted to know for sure would this be a debugging nightmare later. I didn't think about exactly as how you put it though. Maybe a "contact_jobs" will lead to more maintainability. – mardubbles Apr 15 '22 at 02:33
  • @mardubbles I dont suggest `contact_jobs`, because this might look like a junction table witch contains foreignkeys from both table, and what if you just want raw data from this junction table, what the route should be – Josh Lin Apr 15 '22 at 05:45
  • @mardubbles `populate-with-relation/tbl1/tbl2,tbl3?where` might be better, but when nested with complicate relation it looks bad, maybe a json in body goes better, but that's not about rest anymore, still I believe `contact/:id?populate=jobs` shallbe enough and debug shall be easier, if you dont insist restful, single route with query json in body also works fine, graphql does that way – Josh Lin Apr 15 '22 at 05:58
0

REST doesn't care what spelling conventions you use for your resource identifiers. As long as your spellings are consistent with the production rules described by RFC 3986, you're fine.

If you have a lot of similar resources, it can be convenient to use URI Templates and variable expansion to define your family of identifiers. That allows clients to use general purpose libraries to construct your identifiers, and allows you the option of using a general purpose library to parse information out of the target URI for each request.

Beyond some purely mechanical concerns (ex: using the proper escape sequences), it really doesn't matter whether you use variable expansion in the query, or in path segments, or multiple times in each, or whatever.

There are trade offs to consider -- path segments combine well with relative resolution; application/x-www-form-urlencoded key value pairs combine well with HTML forms.

Beyond that, the machines don't care. So choose any spelling that makes things easier for some people that you care about.

VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
  • "REST doesn't care what spelling conventions you use for your resource identifiers." ... Okay I will be going with this strategy (+1), because in no way can I use a "single table" as a resource if I'm pulling data from different tables to satisfy the "resource". For me to debug later the "resources" will have to be virtual name assignments on key functionality of the API. Better to do it this way. – mardubbles Apr 15 '22 at 02:59
  • Not to say I would spell the resource as the exact table name. But treating a "resource" as anything the api can handle is a better way to think about it. Appreciate it. – mardubbles Apr 15 '22 at 03:01
  • "Any information that can be named can be a resource" -- Fielding, 2000. – VoiceOfUnreason Apr 15 '22 at 03:03