5 ms·

This is my approach as well. Works very well with an event-sourcing model. It is much easier to capture user intent with POST /api/customer/1/change-address-du

This is my approach as well. Works very well with an event-sourcing model. It is much easier to capture user intent with POST /api/customer/1/change-address-due-to-move { "address_1": "...", "address_2": "...", ... } than with: PUT /api/customer/1 { "address_1": "...", "address_2": "...", ... } Also, GET /api/resource/action is nice place for a payload describing the expected inputs to the action. Link it all together with hypermedia and you really have something ;) Believe others are coming around to this line of thought: ThoughtWorks included "REST without PUT" onto their technology radar earlier this year.

Zikes 11y ago
How about POST /api/customer/1/address {"address": "..."}
- deleted 11y ago
  [deleted]
- wise_young_man 11y ago
  POST is used to create a resource. PUT is used to update an entire resource. PATCH is to partially update a resource.
  - oldmanjay 11y ago
    Sure, just so long as you realize that is a convention and not a law.
    - hartror 11y ago
      It isn't just a convention, the reasons for doing this are laid out in the HTTP 1.1 spec and assumed by servers, proxies, browsers, clients and developers. For example if I hand someone an API with a URI that accepts a PUT they know they can safely retry PUTs to that endpoint because the server state will always end up the same.
      - oldmanjay 11y ago
        there is nothing in the specification of the PUT verb that indicates it is meant only for complete replacement of an existing resource. in fact, the RFC specifically has a section describing the semantics of creation using PUT. therefore, either your stance is trivially falsified, or you were replying to me out of context, which is intellectually dishonest. https://tools.ietf.org/html/rfc7231#section-4.3.4 https://tools.ietf.org/html/rfc7231#section-4.3.4
        hartror 11y ago
        > The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload. So PUT either creates or replaces a resource. Definition of replaced: > 1. take the place of. Source: https://www.google.com.au/search?q=define%3A+replaced https://www.google.com.au/search?q=define%3A+replaced It is pretty clear to me that the spec says PUT completely replaces the state of a resource. So not just a convention but what the spec says. BUT lets take it further. Lets say you do allow partial updates with a PUT. Can you guarantee that your resource's state will always be internally consistent? Say you have two clients, both doing partial PUTs and do the following: Client 1: GET /foo Client 2: GET /foo Client 1: PUT /foo {'bar': 1} Client 2: PUT /foo {'baz': 2} Is the foo resource is a consistent state? For some applications it could be but for many it won't be. And worse for some applications it may not be idempotent and a client's proxy is going to silently retry a PUT that isn't safe to do so. So by allowing partial PUTs we're requiring the developer to consider all combinations a resource could be updated. They then need to communicate the valid combinations to any clients. OR they can split the resource up finer grained resources, each one representing a valid PUT.
        oldmanjay 11y ago
        so since the post I replied to said that POST is for create, and PUT is for complete replacement, and you just indicated that PUT can be used in ways that the OP did not, and I objected to the OP's prescriptivism, you agree with me despite your stance of arguing with me about it.
eyko 11y ago
Why not PATCH /api/customer/1 {"address_1": "...", "history": "moved", ...} (i.e. send your intent as a parameter that may not necessarily get saved in this resource)
- jameshart 11y ago
  Because now your client needs to know what parts of the object need to be updated when a customer moves, and explain to the server exactly what those changes should be; and the server has to know how to validate that the client made a valid set of changes to the customer object. If you instead have the client tell the server what kind of change you want to make, and provide the parameters to the operation, the server can do everything that needs to be done and the client doesn't need to care.

Zikes 11y ago

How about POST /api/customer/1/address {"address": "..."}

deleted 11y ago
[deleted]
wise_young_man 11y ago
POST is used to create a resource. PUT is used to update an entire resource. PATCH is to partially update a resource.
- oldmanjay 11y ago
  Sure, just so long as you realize that is a convention and not a law.
  - hartror 11y ago
    It isn't just a convention, the reasons for doing this are laid out in the HTTP 1.1 spec and assumed by servers, proxies, browsers, clients and developers. For example if I hand someone an API with a URI that accepts a PUT they know they can safely retry PUTs to that endpoint because the server state will always end up the same.
    - oldmanjay 11y ago
      there is nothing in the specification of the PUT verb that indicates it is meant only for complete replacement of an existing resource. in fact, the RFC specifically has a section describing the semantics of creation using PUT. therefore, either your stance is trivially falsified, or you were replying to me out of context, which is intellectually dishonest. https://tools.ietf.org/html/rfc7231#section-4.3.4 https://tools.ietf.org/html/rfc7231#section-4.3.4
      - hartror 11y ago
        > The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload. So PUT either creates or replaces a resource. Definition of replaced: > 1. take the place of. Source: https://www.google.com.au/search?q=define%3A+replaced https://www.google.com.au/search?q=define%3A+replaced It is pretty clear to me that the spec says PUT completely replaces the state of a resource. So not just a convention but what the spec says. BUT lets take it further. Lets say you do allow partial updates with a PUT. Can you guarantee that your resource's state will always be internally consistent? Say you have two clients, both doing partial PUTs and do the following: Client 1: GET /foo Client 2: GET /foo Client 1: PUT /foo {'bar': 1} Client 2: PUT /foo {'baz': 2} Is the foo resource is a consistent state? For some applications it could be but for many it won't be. And worse for some applications it may not be idempotent and a client's proxy is going to silently retry a PUT that isn't safe to do so. So by allowing partial PUTs we're requiring the developer to consider all combinations a resource could be updated. They then need to communicate the valid combinations to any clients. OR they can split the resource up finer grained resources, each one representing a valid PUT.
        oldmanjay 11y ago
        so since the post I replied to said that POST is for create, and PUT is for complete replacement, and you just indicated that PUT can be used in ways that the OP did not, and I objected to the OP's prescriptivism, you agree with me despite your stance of arguing with me about it.

eyko 11y ago

Why not PATCH /api/customer/1 {"address_1": "...", "history": "moved", ...} (i.e. send your intent as a parameter that may not necessarily get saved in this resource)

jameshart 11y ago
Because now your client needs to know what parts of the object need to be updated when a customer moves, and explain to the server exactly what those changes should be; and the server has to know how to validate that the client made a valid set of changes to the customer object. If you instead have the client tell the server what kind of change you want to make, and provide the parameters to the operation, the server can do everything that needs to be done and the client doesn't need to care.