CODEWITHSUNDEEP
restapi-design
user1578872
user1578872

Reputation: 9018

REST end points - Best practice

I have the following REST end points and not sure if it is following the best practices. Different sites says different things. So wanted to validate here.

GET - /api/v1/service/prj             --> To get projects for the logged in user

GET - /api/v1/service/prj/upcoming    --> To get upcoming projects for the logged in user

GET - /api/v1/service/prj/upcoming/all --> To get all projects for admin user

GET - /api/v1/service/prj/{prj_id}   --> To get all projects for admin user

GET - /api/v1/service/prj/usr/{user_id}

GET - /api/v1/service/prj/usr/all

GET - /api/v1/service/prj/usr/{user_id}/upcoming

GET - /api/v1/service/prj/usr/{user_id}/open

GET - /api/v1/service/prj/details/{prj_id}

Here, the problem is,

GET - /api/v1/service/prj/upcoming

GET - /api/v1/service/prj/{prj_id}

In Spring router, if i place the 2nd one first, the /prj/{prj_id} will be matched for /prj/upcoming. So trying to understand the best practice.

I was thinking tht other route like,

insted of /prj/comping use prj-upcoming. Please help me with the best practice here.

Also, using underscore for path param and query param.

Like, {prj_id}. But, I see some links using prjId. What is the bet practice for using path and query param?

Upvotes: 0

Views: 179

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57194

REST doesn't care what spelling conventions you use for your resource identifiers, as long as those conventions are consistent with the production rules defined in RFC 3986.

In particular: from the point of view of a REST component, identifiers are semantically opaque, you can use any identifier to reference any document you like.

GET - /api/v1/service/prj/upcoming
GET - /api/v1/service/prj/{prj_id}

This is a routing problem; clients don't care, but as you've discovered your routing implementation does care.

What can you do?

  • You can change your spelling conventions - which is fine
  • You can change your routing implementation - which is fine
  • You can write your own logic to resolve the ambiguity - which is fine

The thing that you can't do, in any sane system, is to allow a single identifier to refer to two different resources.

So you can have {prj_id} and upcoming in the same place so long as it is clear in your internal schema that "upcoming" is never a valid prj_id (whether that be because prj_id is always a number or always a UUID, or because reserved words aren't allowed as prj_id and "upcoming" is a reserved word... whatever you like).

Upvotes: 3

Related Questions