5 ms·

> "Only use nouns in your resource URLs, avoid endpoints like /addNewUser or /updateUser . Also avoid sending resource operations as a parameter. Instead explai

> "Only use nouns in your resource URLs, avoid endpoints like /addNewUser or /updateUser . Also avoid sending resource operations as a parameter. Instead explain the functionalities using HTTP methods: GET Used to retrieve a representation of a resource. POST Used to create new new resources and sub-resources PUT Used to update existing resources PATCH Used to update existing resources. PATCH only updates the fields that were supplied, leaving the others alone DELETE Used to delete existing resources" This used to be hip and cool and "look ma, i'm modern, i'm doing it REST-style!", but i don't think the fad holds anymore. In real life, you are going to do much more "operations" to a "resource" than just "retrieve", "create", "update", or "delete", and thus you need to use operation names. It makes more sense to always send the operation name and to standarize on operation names. Also operation names can be more explicit and unambiguous. It is, for me, a very bad idea to mix up your business model semantics (actions performed on the business model) with the semantics that belong to the OSI-model application layer (HTTP methods: GET, POST, PUT, PATCH...).

partycoder 9y ago
(Removed this comment as it was incorrect)
- yes_or_gnome 9y ago
  No. HEAD is the same as GET, but the server should not return a response body. The response code and headers should all be the same. This is to guarantee that a path is serviceable, response body size, and for verifying the client's cache.
  - partycoder 9y ago
    You are correct, sorry about that. Removed my comment to not spread incorrect information.
HatchedLake721 9y ago
Do both together. Use GET/POST/PATCH/DELETE for the simple CRUD on the resource. Then, put your actions under POST /resource/{id}/actions/{action}, e.g. `/repositories/1/actions/archive`, `/users/1/actions/ban`, `/customers/1/actions/credit-score-with-bank-of-xyz`, etc
- always_good 9y ago
  I don't see why you'd want the /actions/ segment at all. That's like using a /resources/ prefix at the start of every endpoint.
- urethrafranklin 9y ago
  I find the "/actions" slug a bit goofy and unnecessary. Why not just put it at e.g. "/repositories/1/archive"? Additionally, why not maintain restful semantics by using PUT (or more likely, PATCH) instead of POST (which implies creating a new resource)? And "/customers/1/actions/credit-score-with-bank-of-xyz" sounds a lot like a GET request.
  - denisw 9y ago
    I agree about /actions, it is unnecessary. However, for these kinds of "action resources", POST is definitely the best-matching request method. It does not mean "create a resource" (although this is one case it is often used for), but "process this request in your custom resource-specific way". The HTTP RFC formulates it like this [1]: > The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics. Given that what an action resource does is, by definition, resource-specific, POST fits perfectly. [1]: https://tools.ietf.org/html/rfc7231#section-4.3.3 https://tools.ietf.org/html/rfc7231#section-4.3.3
  - HatchedLake721 9y ago
    Because there could be related resources, e.g. "/repositories/1/users", or "/users/1/comments". I agree it's not necessary, but having /actions just makes it more clear. For example: "/repositories/1/bans" shows me all bans "/repositories/1/ban" ban action I know it's a bad example, but you could end up with other similar related resource and action names that could increase chances of silly mistakes.
richardknop 9y ago
This is also something I think about. It seems that this approach is slowly getting out of fashion and people are starting to prefer APIs similar to SOAP (but JSON based instead of XML). However if it is a HTTP based API, I'd still think it should be exposed in a way to use HTTP methods correctly. As they align quite well with what web applications will mostly do (CRUD operations). If you need to do some extra operation, you could create a resource which wraps that operation, for example triggerScheduledJob could be POST /scheduled-job-triggers with body describing parameters to triggerScheduledJob method. Another approach seems to be to use protocol buffers and something like gRPC. This is good for command line tools or internal communication between services but still, public API exposed over HTTP protocol should probably be designed to accommodate HTTP verbs.
- urethrafranklin 9y ago
  Actually, I think it is more like simple RPC than SOAP. I'm personally betting big on GraphQL.

partycoder 9y ago

(Removed this comment as it was incorrect)

yes_or_gnome 9y ago
No. HEAD is the same as GET, but the server should not return a response body. The response code and headers should all be the same. This is to guarantee that a path is serviceable, response body size, and for verifying the client's cache.
- partycoder 9y ago
  You are correct, sorry about that. Removed my comment to not spread incorrect information.

HatchedLake721 9y ago

Do both together. Use GET/POST/PATCH/DELETE for the simple CRUD on the resource. Then, put your actions under POST /resource/{id}/actions/{action}, e.g. `/repositories/1/actions/archive`, `/users/1/actions/ban`, `/customers/1/actions/credit-score-with-bank-of-xyz`, etc

always_good 9y ago
I don't see why you'd want the /actions/ segment at all. That's like using a /resources/ prefix at the start of every endpoint.
urethrafranklin 9y ago
I find the "/actions" slug a bit goofy and unnecessary. Why not just put it at e.g. "/repositories/1/archive"? Additionally, why not maintain restful semantics by using PUT (or more likely, PATCH) instead of POST (which implies creating a new resource)? And "/customers/1/actions/credit-score-with-bank-of-xyz" sounds a lot like a GET request.
- denisw 9y ago
  I agree about /actions, it is unnecessary. However, for these kinds of "action resources", POST is definitely the best-matching request method. It does not mean "create a resource" (although this is one case it is often used for), but "process this request in your custom resource-specific way". The HTTP RFC formulates it like this [1]: > The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics. Given that what an action resource does is, by definition, resource-specific, POST fits perfectly. [1]: https://tools.ietf.org/html/rfc7231#section-4.3.3 https://tools.ietf.org/html/rfc7231#section-4.3.3
- HatchedLake721 9y ago
  Because there could be related resources, e.g. "/repositories/1/users", or "/users/1/comments". I agree it's not necessary, but having /actions just makes it more clear. For example: "/repositories/1/bans" shows me all bans "/repositories/1/ban" ban action I know it's a bad example, but you could end up with other similar related resource and action names that could increase chances of silly mistakes.

richardknop 9y ago

This is also something I think about. It seems that this approach is slowly getting out of fashion and people are starting to prefer APIs similar to SOAP (but JSON based instead of XML). However if it is a HTTP based API, I'd still think it should be exposed in a way to use HTTP methods correctly. As they align quite well with what web applications will mostly do (CRUD operations). If you need to do some extra operation, you could create a resource which wraps that operation, for example triggerScheduledJob could be POST /scheduled-job-triggers with body describing parameters to triggerScheduledJob method. Another approach seems to be to use protocol buffers and something like gRPC. This is good for command line tools or internal communication between services but still, public API exposed over HTTP protocol should probably be designed to accommodate HTTP verbs.

urethrafranklin 9y ago
Actually, I think it is more like simple RPC than SOAP. I'm personally betting big on GraphQL.