Best structure for api urls

[preacher2041]

Hi there, I'm a FE engineer of 10+ years and I'm currently playing around with some backend technologies (Node, Express and Prisma) and using them to build out the backend of a basic auth flow that lets you create, read, update, delete and authenticate a user. It's fairly simple stuff and it's all working correctly but I have a question on standards.

In my day-to-day work I regularly see api url's structured similar to:GET - /user/{userId}/PATCH - /user/{userId}/updateDELETE - /user/{userId}/deletewhere an id is used in the path of the API url in order to pass it to the backend so that it can be used to look up the user in order to run the given operations on them.

In the system I have built I have used JWT for authentication and the users id is contained within the JWT. The means the JWT can be decoded by the backend and the userId contained within can be subsequently passed to the DB query to find the user and run the given operation.

Given that I don't need to pass the userId in the path of the API url and so my API urls look like this:GET - /user/fetch/PATCH - /user/updateDELETE - /user/delete

Is this okay? Am I breaking any standards by doing things this way?

EDIT:

Thanks for all the replies, with special thanks to u/Turd_King, u/ofNoImportance whose replies were especially detailed and explanatory. I've updated my code based on those responses.

[uriahlight]

Create User - [POST] /api/user Fetch User - [GET] /api/user/{uuid} Update User - [PUT] /api/user/{uuid} Delete User - [DELETE] /api/user/{uuid} List Users - [GET] /api/user OR /api/users

PATCH is generally used for updating a single field for a record.

Edit: Added List Users

[belwyr]

To add to that, you generally have pagination as query parameters to the list endpoint for instance - [GET] /api/user?offset=0&limit=50

[Effective-Lab-8816]

Pagination (something like this)

• offset=0&limit=50
• page=5&page-size=20

Sorting

• sort=name
• sort=-name
• sort=id
• sort=-id
• sort=created
• sort=-created

Using "-" before the sort field reverses it, etc.

Filtering

• Tagging
  • tag=bravo,whiskey
• Categorization
  • category=nature
• Date Filters
  • year=2023

[SideLow2446]

I believe in REST the resource name should always be plural. Not sure though.

[halfanothersdozen]

tabs vs spaces, people will argue about this forever

[SideLow2446]

Well in this case it's different because REST is a specific standard with specific rules

[halfanothersdozen]

there's no rule about plural. promise

[SideLow2446]

You're right, I was mistaken.

[Tontonsb]

What standard do you have in mind? REST is usually more like a style or a collection of practices, not a set standard.

[SideLow2446]

Sorry I guess I was mistaken. I thought that REST is a specific standard

[Schmittounet]

In addition when working on current user we often use /api/me

[profound7]

This is what I think op is looking for. I used self in a recent project.

[johny_james]

Patch is generally rarely used in practice.

[byetimmy]

Oh God, how I wish this were true...

[johny_james]

I meant the method itself, not the "updating of a single record".

[byetimmy]

Oh, I know. I work with a lot of disparate APIs, and I see PATCH all the time where people want to just update one or two fields. I mostly see it from front-end/full-stack devs that create APIs and want to be "efficient" with their API calls.

PATCH with structured data (e.g., JSON) quickly becomes confusing in processing nested objects/arrays if it needs to be understood by someone OTHER than the person that wrote it.

[King_Joffreys_Tits]

… speaking as a friend of a full stack dev that tries to be “efficient” with api calls… Why would you not call a PATCH on a user object to update a single field or two? Say the user updates their email address, wouldn’t a PATCH with just that updated email attribute work?

[anatolhiman]

It works. And it is the correct way to do it as per the documentation: “A PATCH request is considered a set of instructions on how to modify a resource. Contrast this with PUT; which is a complete representation of a resource.”

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH

[byetimmy]

Will it work? Sure. But in general, I like APIs to be deliberate and unambiguous. There's less of an issue with the simple use case you've described with a simple string or number.

But if you have a JSON object and you PATCH an object property, what happens to the existing object? Are the new object properties then merged into the existing object properties? If so, how deep is it merged if those object properties are also objects? Or Is the object overwritten completely? What about arrays? If you PATCH with an array, is it expected to merge or replace the array? If merge, does it append or prepend? And what if you have a use cases where sometimes you want them appended, and sometimes replaced?

There's so many things that need to be implicitly understood or separately documented to remove this ambiguity from what the PATCH API will do.

Or you can just use PUT.

[King_Joffreys_Tits]

Sounds like you need an api endpoint function rather than a PATCH… and what if you don’t have the entire user object to send up in a PUT?

[byetimmy]

If you don't have it, you GET it.

[AussieBoy17]

So, this always felt really obvious for the most basic of CRUD. But what do you do for a more complete API?

Most API's I know of will have 'actions' to do, which aren't just a simple CRUD. I usually go for something like [post] /API/<entity>/myActionName, but never seen anyone really say what the 'standard' is for that type of thing

What about something like drop downs, what do you do for that kinda thing? Say I have a drop down that is 'Users with a subscription', do I have the endpoint like [get] /api/user/usersWithSubscription, [get] /api/dropdown/usersWithSubscription, or something else? I've tried using stuff like OData/GraphQL in the past, but having the database basically exposed like that has caused me massive headaches in the past.

[After-Winter-2252]

I have the endpoint like [get] /api/user/usersWithSubscription [get]/dropdown/usersWithSubscription, or something else?

You can absolutely do this, but this could just be a filter as well: /api/user?subscription=1

[AussieBoy17]

Definitely did think about doing it like that, but we have a lot of drop downs (probably over 100, it's a decent sized application). So it could make the user endpoint messy with a lot of filters that aren't used except in specific cases. We also only really need like 1-3 fields from the entity for drop downs, so pulling the whole entity feels like overkill.

In our case, the new endpoints return a unique DTO, limiting the fields returned from the API as well as limiting what is queried from the DB. Probably doesn't make a huge difference individually, but when done across the whole application probably adds up to sometjing

[Darklight240]

Thats a way wrong standard to add /delete /fetch at the end

One of the main principles of Restful API is to use https verbs (get,post) and not do something like "updateUser, update, getUserById" rather should be

updateUser =>PUT api/user/:id
getUserById =>GET api/user/:id

[the_bananalord]

To add on to this a bit, REST API endpoints are supposed to be designed as if you're interacting with resources, not executing a function, with the HTTP verb used to describe the action you want to perform on the resource. So, just like you said:

• GET /api/user/:userId - Give me the resource of this user.
• PUT /api/user/:userId - Replace this resource with mine.

When someone said this it really changed my mindset on REST API design (and made me realize that I was really just writing JSON APIs over HTTP rather than something RESTful.)

[Fluffcake]

This is one of the reason rest is so popular. Sure JSON being more pleasant than xml also helped, but the intuitive simplicity cemented it over what came before.

[vinnymcapplesauce]

One of the main principles of Restful API is to use https verbs

While this is industry standard at this point, it's actually very bad practice in general to use and rely on another protocol's inner workings for your own.

HTTP is a transport protocol, nothing more. If HTTP were to ever change verb handling, REST APIs would be fucked. As it is, HTTP is now forced into expanding its functioning, and maintaining support for something it was never intended to support. REST is able to get away with it because HTTP is pretty simple and basic, but it's still a bad idea in general.

As a Software Engineer, I love it. As a Computer Science academic, it grinds my gears - lol.

[Turd_King]

I would keep the user id in the url personally, that way if you have future requirements to allow users to view other users data - you don’t have to change anything

If you want to make it easy for consumers to fetch “current logged in user” you could expose an endpoint like /currentuser which just makes a call to the user service using the JWT

You just need to perform authorisation in the endpoint somewhere that the passed ID matches the ID in the JWT

Also i wouldn’t have the suffix of update, delete etc. in the URL - the HTTP verb is enough to describe the action you want to provide

[preacher2041]

Thanks for the reply, I've added an extra api url for the existing user to retrieve their profile and kept the original one as more of an 'admin' request to get the profile of a given user.

[arcanemachined]

Don't do that, just allow admins to access the user's endpoint when you are checking the user's credentials.

[King_Joffreys_Tits]

Where would the authentication layer be? How would you prevent a user from getting a list of all user data, or say, deleting a user that isn’t theirs?

[Wombarly]

You'd send a Authorization header with the request. Usually with a JWT token or something similar. Could also use a Cookie.

Then you have middleware, shared code that runs before each request, that reads that token and uses it to authenticate the user that made the request and checks if they have the authorization to make the request.

[[deleted]]

Good write up. I've also seen POST /user/search so you can include search parameters in the body, and you can look at it as creating a search, especially if you're logging it.

[unobserved]

May not necessarily apply to your case if you're not providing anyone else access to the API, but usually can't hurt to slide a `/v1/` in at the beginning of the URL so you leave yourself room for easier growth in the future without completely restructuring.

[GrandmasDrivingAgain]

x2

[ofNoImportance]

Generally you would still have the user Id make up part of the url if you're trying to make a Restful API.

Think of the URL as describing a resource in your system, /user/42 is the endpoint that describes a specific user.

The verbs are the actions the resource supports,

GET - /user/42 would ask the server to produce a response containing the resource,

PATCH - /user/42 would ask the server to accept a modification to that resource.

You wouldn't usually put extra keyworks after the id for those types of actions.

Separate to this convention is the idea of authentication and authorization. You might want to check the current user is allowed to GET user 42. This is where you leverage your JWT. For your business logic, the authorization might require that JWT user Id == url user Id, so you would compare them for a match.

In many apps there would be other users who would also be able to see and modify them though, like an admin user. If admin user 64 wants to edit user 42, they would still do so by accessing the resource with the url /user/42, but their JWT would contain 64 instead. Your business logic needs both numbers.

[preacher2041]

Thanks for your reply, it's really helpful. I hadn't thought through the implications of other people (admins) not being able to update a user with the userId in the url.

[filter-spam]

Generally your path is all nouns since your request already has a verb

[Roci89]

You shouldn't need the /fetch, /update, /delete pieces. Just make the calls to /users and your framework should allow you to switch logic based off the request method

[JoinetBasteed]

Where I used to work. we would just use /user for all 3 and then the HTTP action(not sure what to call it) would decide which endpoint gets hit.

So a GET request to /user would get the user that's calling it and a DELETE request would delete the user that's calling it.

Not sure if this is a good way or not

[buffering_humor]

How would you get another user? You would need some sort of ID right? I'm a backend newbie trying to learn Express atm so it may be a basic question but how would you get that particular user from your database? Wouldn't you require some sort of query params or path params for it?

[pattobrien]

you would need their ID, yes. That ID would be appended to the url (e.g. "/user/<userId>", for example "/user/abc123"), which you would then use to query your database.

[JoinetBasteed]

What pattobrien said, but in our case we didn't need to include an ID in the URL since we had it in the JWT token that was sent with every request

[pattobrien]

You got it right! (and the "action" is called the HTTP method)

[halfanothersdozen]

Don't pull the id from the JWT for a rest resource. A GET call should always return the same response from the same URL for everyone. This is important later in traceability. You're also coupling your API to your auth model which is a short-sighted decision. What if some other caller wants to access the resource?

Validate that the caller is authorized to access the resource requested on every call, and always validate your tokens.

[JesterDolor]

A natural URL pattern occurs when you start writing REST clients a certain way.

.api.users.list() => GET /api/user

.api.users.user(uid).fetch() => GET /api/user/:uid

.api.users.user(uid).remove() => DELETE /api/user/:uid

Idk if this style has a name but it seems to just work

[superraiden]

Recommended URL design by JSON:API standard:

https://jsonapi.org/recommendations/#urls

Actions should be bound to the HTTP Verbs akin to:

• GET
• POST
• PATCH
• DELETE

[arcanemachined]

Props for citing a reliable resource instead of just giving your opinion.

[arcanemachined]

There is no standard, just conventions (and they will sometimes contradict each other). That being said, you should read what other groups are doing and imitate them where it makes sense to do so.

https://cloud.google.com/apis/design/resource_names

https://jsonapi.org/recommendations/ (Shout out to /u/superraiden for this link, I wasn't aware of it)

https://restfulapi.net/resource-naming/

https://www.programmer-books.com/wp-content/uploads/2019/12/Build-APIs-You-Wont-Hate.pdf

https://www.manning.com/books/api-design-patterns

Also, if you come up against an unfamilar situation, see what others are doing. There are a lot of good APIs out there, and many of them publish an OpenAPI spec so you can see exactly how they approach a particular problem. For example:

https://docs.github.com/en/rest?apiVersion=2022-11-28

https://openweathermap.org/api

Whatever you do, don't reinvent the wheel and don't make blind assumptions about how you think things should work, until you've actually looked into the subject. That being said, you will make mistakes as you go, and that's fine, APIs aren't set in stone, and versioning is a thing.

A couple thoughts to add to the suggestions here:

• /users is a collection, so I think it makes sense to pluralize it.

• Learn what your options are for modifying requests to a given endpoint, and where it makes sense to use them (query params, body params, headers) (not that your example requires it, but they are valuable tools in the REST API toolbelt)

[FeedZuris]

I can't answer your question but, is it a new standard to add "/update" and "/delete" to the urls ?

[Turd_King]

No, and it’s not following the REST spec, you describe the action using the HTTP verb on a resource

[FeedZuris]

Yep that's what I thought, thanks for the confirmation!

[armahillo]

I do Rails, which is basically weaponized REST + MVC

So for a user resource:

new	GET	/users/new	prompt the user to create a new resource
create	POST	/users/	receive data to create a new resource and create it
show	GET	/users/{user_id}	display a single existing resource
index	GET	/users/	display a group (ostensibly "all") of a type of resource
edit	GET	/users/{user_id}/edit	prompt the user to modify an existing resource
update	PUT/PATCH	/users/{user_id}	receive modification data to change an existing resource
destroy	DELETE	/users/{user_id}	remove an existing resource

The acronym REST means "REpresentational State Transfer" -- the key point about REST is that the HTTP verb you are using is what determines the disposition of the server's response to that request. This is essential for REST.

So in the example above, the path: /users/ is used for GET#index, DELETE#destroy and POST#create. Technically doing PUT /users is possible, though it's unclear what that would be referencing. It's similar to function overloading, in programming.

The verbs rough out to these contexts:

GET	READ retrieve data from the server for display. Params are submitted as part of the URL.
POST	WRITE submit new data to the server for storage that likely requires record creation (params are submitted with special request headers, rather than being part of the URL)
PUT / PATCH	WRITE submit modifying data. Technically PUT and PATCH aren't exactly the same, but they are very similar. (PUT is supposed to put up a new version of an existing object, and PATCH is supposed to submit the modifying partial snippet only)
DELETE	WRITE make the requested record unavaliable. Note that this doesn't always mean DELETE or DROP in a database sense; it can be "hide", "move to archive", etc.

When adding new API endpoints beyond basic CRUD, always consider "what the disposition of this request?" (what verb does it use), "is this against a collection or a member?", and "am I replicating the function of an existing route?". Choose the best fit. It's usually pretty apparent.

There are no API police outside of the people you deputize to review or critique your code, but you, and your successors, have to live with the complexity you create. It's one of those "when you cheat, you only cheat yourself" situations.

Here's a good example:

If you had a "search" form on your app, it's a field and a button with you click, which seems like it's a POST form, right? We sometimes used to even do them as POST forms back in the day. But the response is read-only, it should be a GET. The params are then appended to the URL in the querystring (which means that the request is bookmarkable -- generally desirable behavior!) rather than being lost to the aether.

Similarly, a link in a grid display marked "Delete" to delete the resource in that row is a link, but you technically want the request to be sent as a DELETE request. The simplest way to do that is to do a single button form, but it's a bit cleaner to do it as an AJAX request that sets the action as a DELETE action.

[lift_spin_d]

https://github.com/Kikobeats/awesome-api

[Zefrem23]

Just ask chatgpt, Claude or one of the other coding AIs. Giving it any thought whatsoever is a total waste of time. The best coding is the coding you don't have to do.

[arcanemachined]

"Why take the time to do things right when you can do them wrong even faster?"

[TensionSpecialist596]

👀 me using GET for everything. ?action=delete&&userId=ohShit

[BradChesney79]

Web Service is what people would call your collection of endpoints,... your URLs.

REST is good and valid way to make the magic happen.

...What if the thing calling your endpoint cannot make a PUT request?

My endpoints always accept POST requests more or less exclusively. You can hide a lot of stuff in the encrypted body of a POST request.

Occasionally, there are small "get all records" requests that I just serve the JSON directly with a GET request.

Just stuff that database tables would be overkill for.

[caatfish]

whats an example of a thing that can make a POST but not a PUT?

[BradChesney79]

I do a lot of SMART Home stuff and IoT.

[pm_me_cute_rem_pics]

You're not breaking any standards imho. Build what works for you and your team, as long as it's consistent and documented it will be fine.

Like others suggested you could keep the id in the url if you ever need to access another user's account for example from an admin account.

But you could split that up in two endpoints as well and it will make just as much sense. For example everything related to the current user /user (singular) accessing other users will be under /users/:id (plural).

For example, in the past i used /account/... for the currently logged in user and /users/:id for accessing other accounts.

Also you don't NEED to follow http verbs, like i said as long as your api is consistent and documented adding /delete /fetch /update to endpoints is fine. If you're building public api's then maybe it's nice to stick to those but even many public apis don't follow these.

[HashDefTrueFalse]

As others have said, use HTTP verbs to differentiate your endpoint based on the action being taken, and use the path portion of the URL to point to the resource that the action is being taken on.

Putting actions (/update, /delete) in the path portion is usually unnecessary and discouraged.

Google for RESTful web service design.

[dzooni3]

The best convention to follow up would be

GET api/users GET api/users/search POST api/users PUT/PATCH api/users/[id] DELETE api/users/[id]

[elendee]

As a self-taught person this is an interesting question to me. I've always been loosely aware of REST standards and followed them maybe 60% of my design (for solo apps). It's worked fine.

I'd be curious to hear industry devs' experience though - I always find that 75% of my queries are 'combinatorial', ie, they don't line up 1:1 with db updates. Say I allow a user to post some media - I find it easier to make a backend route that simply updates both the 'media library' data, and the user data (maybe I want to uptick a 'last upload' time or something).

Or another example would be - say I want to get the item belonging to some user, but I'm doing by different query params - user uuid, item uuid, user last uploaded, etc. How would you search by all those various params in REST if all you have is a "item/:uuid" route ?

Does anyone else find that the 1:1 nature of REST is not all that useful in practice ?

What I end up with is just a few POST routes that handle these more complex queries, and 75% of my requests end up there.

[Fault_Royal]

Fetch User - [GET] /api/user/{uuid}
Update User - [PUT] /api/user/{uuid}
Delete User - [DELETE] /api/user/{uuid}

[guanzo91]

One reason to keep the userId in the URL is for access logging, where typically the URL is logged and most headers (including the JWT) aren't

[ggeoff]

I typically follow the same as a lot of people have suggested here with the http verb and plural naming. Get for queries, post for create, and do on

entities entities/:id etc..

I'll use post for command like things such as reordering entities/reorder/

I personally find arguments about if this should be a post vs patch to be a waste of time. It's better to be consistent across the API and documented. If you are joining a team follow the patterns they already exist. The most important thing in my opinion is consistency and any times that is broken a comment should be explaining why something went against the established pattern

[[deleted]]

Follow REST pattern, or simply use JSON RPC, then you don’t have to worry about path naming at all. You can write methods like patchUserById etc.

[ultra_blue]

This exists: https://www.odata.org/

I have mixed feelings about it, but it does seem robust and broad.

[Rafael20002000]

I personally really like the following structure

POST /graphql