All path resources should be followed by a unique identifier for that path resource

[jsswansonsps]

// CORRECT
api.spscommerce.com/users/{id}
api.spscommerce.com/users-search
api.spscommerce.com/users-export
In this example the element after the /users resource only has one meaning and returns a consistent payload. The "me" is purely a convenience and still references a single user.

// INCORRECT
api.spscommerce.com/users/{id}
api.spscommerce.com/users/search
api.spscommerce.com/users/export
In this example the element after /users has multiple meanings. It no longer returns a single user and has a different function. Also the payload returned lacks consistency when search and export is used. It no longer returns a single user and has a different function. The element after /users MUST always represent an id for this example.

This would be the preferred approach if there isn't a better way to provide the functionality that is needed.

api.spscommerce.com/users/{id}
api.spscommerce.com/users-search
api.spscommerce.com/users-export

References:
https://www.theserverside.com/opinion/RESTful-parameters-antipattern-considerations-for-queries-paths
Snippet
"If the second path parameter represents a city or a location, it should always represent a city or location. A change like this of an indexed parameter on the fly won't be supported by most RESTful API frameworks."

[emirgorodov]

It looks like the idea doesn't contradict existing standards, at least /users-export case is partially covered by actions section.

I would support this approach for some of /users-list like cases. One of the advantages aside from mentioned - usage of /user/search along with user/{id} implicitly implies that the contract of results would be similar for both cases, when in fact listing endpoints frequently offer a different projection of resource. For such specific cases, a dedicated list resource looks appropriate. For simple cases when the model is the same - query params on the same /users resource do the job greatly.

[travisgosselin]

Agreed, I think that as suggested here is generally how many of us think and interpret resource usage and is not in contradiction to the existing standards. The callout here is adding more details to the API standards to direct toward this usage I assume?

Another pattern for this would be:

api.spscommerce.com/users/{id}
api.spscommerce.com/users/_/search
api.spscommerce.com/users/_/export

Where the _ is meant to NULL it out potentially. Not a fan, but just demonstrating.

@emirgorodov sounds like you are in support unless an action endpoint (i.e. /users/search) has the same model as /users?

I'm struggling a bit with /users/search vs /users-export as it removes the hierarchical nature of the URL, and from a documentation/design spec perspective, it would often place the user export functionality as a separate tag/resource entirely.

I see it not being ideal, but in general, I wonder if the examples posted are just poor design around resources? For example:

• /users/search - a general idea as @emirgorodov mentions IS TO NOT HAVE this, use the filtering as defined in the standards on /users
• /users/export - I would avoid an export for users, and use the /users collection endpoint to retrieve them with additional query parameters... and if a change in format is needed then a different media-type describing the non-json format you want.

[jsswansonsps]

Yes I would agree with comments here. We have to be very cautious when adding new urls that support things like search or export as they could potentially be handled in different ways as previously stated. As an example, the export feature could even be designed as such get /exports?type=users&format=pdf where it returns a standard set of attributes with a PDF file or whatever formats are needed.

[travisgosselin]

I think I'm onboard in general though that more instructions on the URL structure page should include recommendations NOT to have conflicts between paths with static and unique values.

@jsswansonsps any chance you feel like proposing a PR with the updates at your convenience?

[jsswansonsps]

@travisgosselin I defer to you as the official wordsmith :) I'd end up stammering through it. I know you can make it sound intelligent.

[travisgosselin]

@ravisaluru has offered to put together a proposal and update via PR. @jsswansonsps hoping you can support Ravi in that.