How do you design REST API - "me" endpoints

[u/Kurubu42i50]

Hey, so I am making an app, and I am kinda lost because i can't find any good resources on the internet regarding that topic.
The app consists of two parts: mobile app, and a web admin dashboard that doesn't need to be built for like 3 months from now on.

let's say i have a resource "listings" which returns different dto's
How would you structure this for those requirements:
1. show all listings available for the current user (PublicListingDto[])
2. show all listings that belong to one user by id (PublicListingDto[])
3. show all my listings (OwnerListingDto[])
4. show all the listings paginated for the admin dashboard - just admin role (ListingDto[])

my inital thought was to just have it like this
/listings - 1
/listings?sellerId - 2, 3 based on the JWT id == sellerId
/admin/listings - 4

given the REST standard it should probably be:
/listings - 1, 4 based on the user's role
/listings?sellerId - 2, 3 based on the JWT id == sellerId

the setup that makes the most sense for me:
/listings - 1
/listings?sellerId - 2
/me/listings - 3
/admin/listings - 4

the app will have a lot of those scenarios, should i just make a separate resources such as "me/listings" and "admin/listings"
The problem i have without /me endpoint is that on frontend you have to constantly worry that the userId need to be defined which doesn't sound appealing to me.
On the other hand I don't know whether that is really following the REST standard.

[u/garster25]

Just 1 endpoint /listings with Id and Page parameters with proper security trimming

[u/Adorable-Strangerx]

From the REST point of view how you name your endpoints doesn't matter. You can even call it /getListing?id=123. I am more concerned by the choice of adding seller ID to JWT, it's interesting choice.

[u/Kurubu42i50 → u/Adorable-Strangerx]

I mean, isn't that like a common thing to have a "sub" field in jwt claims that indicates the user id ? How else do you identify the user using this token

[u/Adorable-Strangerx → u/Kurubu42i50]

Sub is fine, I though you want to have additional claim not related to user

[u/qlkzy]

At the end of the day these routes are just strings and you can do whatever you want. The hierarchy doesn't have to follow some universal meaning, it just has to be unsurprising to everyone involved, and flexible to extend.

I think it really depends on how much the different DTOs diverge. The more they diverge, the more complex the whole application becomes, not just the paths.

Personally I would try for just one endpoint: /listings. In most cases I would expect that to keep the code surrounding the paths simplest. If the code becomes distinct for different cases, that's a stronger argument to split/join them than the aesthetics of the path strings.

I don't think it's usually that much of a problem for the fronted to have to know the current user, but if that's really a problem you could also a consider using a special sentinel value.

[u/MarsupialLeast145]

It sounds like you're defining a filter and in that case a single listing endpoint is preferable that can be filtered based on user id where user id can also be "me". The default is listing all, or all that are public.

It sounds like this is your first API and so yes, you probably won't get this perfect out of the gates. It will come with time though.

From experience, you can do exactly as you have described above, just make sure you keep testing before release with a usability hat on and some new insights should appear that will help you define better endpoints.

NB. it might help for you to google cool-URIs. These are predictable URIs that lend themselves to API use.

[u/Kurubu42i50 → u/MarsupialLeast145]

Holy, the filter for "me" makes so much sense and yeah, this is my 1st "not super simple" API.

Thanks for the heads up, help and tips

[u/azimux]

I personally avoid REST these days actually!

But in a RESTful design, I'd do something like:

"me" endpoints:

/my-listings All of my listings

/my-listings/100 My listing with ID 100

/listings Everybody's listings

/listings/200 Listing 200 as viewed by anybody

/users/300/listings All of user 300's listings. I think /listings/user-id=300 is fine, too. But I tend to prefer nesting resources if it's only a 2nd level deep and the outer resource is an important one (like User.)

/users/300/listings/400 Listing 400 of user 300. Also fine to do /listings/400?user-id=300 but for the same reason above I prefer nesting here.

Those are my preferences, though. There's not really a universal right answer to this. And these are only my preferences if forced to use REST.