Search code examples
restputidempotent

REST API Design - Resource relationships and Idempotency of a PUT request: What, exactly, is meant by a full resource representation?

I understand that for partial updates, an action must be taken that is not idempotent. To that end, a valid approach is to make a POST request to that resource.

I have a question though about related resources. For example imagine the following resources with their properties:

  1. Accounts
    Id
    Name
    Account #
    Users (a collection)

  2. Users
    Id
    Name

Now imagine I want to make a partial update to an Account - for example, to change the Account's name.

I could make the following request as a valid partial update: 

POST /account/id/123

{
    "name" : "My New Name"
}

My question is regarding a full PUT request which must be idempotent and must include a full representation of the resource.

Could I do the following as a valid idempotent request?

PUT /account/id/123

{
    "name" : "My New Name",
    "accountNumber" : "654-345-4323"
}

Is that considered a valid, idempotent action? I've included all the top level "Account" information, but I question it because I didn't post all the USERS that belong to the account as well.

In order to be a valid idempotent request, would I need to include all of it's sub resources as well in the PUT request?

Solution

  • An easier way to understand is to consider that the PUT method ignores the current state of the target resource, so a "full resource representation" means that it must have all data needed to replace the existent resource with a new one.

    In your example, that could be a valid full representation for an account with no users.

    It's fine for the server to assume default values when something is missing, but that should be documented properly as some users might confuse with a partial update.