RESTful API design (connection of resources)

Question

I'm designing an API for my web project (PHP) but run into trouble when modeling relationship between resources with properties. I would like to get some input on how to proceed.

Resources:

• Users.
  • Id.
  • Name.
  • Dogs (relationships).
    • Id.
    • Private (yes or no).
• Dogs.
  • Id.
  • Name.

Relationships:

• Many to many.
  • One user can have many dogs.
  • One dog can belong to many users.
• The relationship can be private or public.

How would you like to update the "private" property of the relationship?

Right now you would have to send a PUT request to .../api/users/{userId} including ALL relationships of that user including the updated property:

(Name can be NULL -> no Update)

• Dogs:
  • Dog.
    • ID : DogA.
    • Private: Yes.
  • Dog.
    • ID : DogB.
    • Private: No. (Updated)

I don't feel comfortable with this approach since I believe that only information that have been changed should be need to be sent to update. My idea right now is therefore to add support for only sending the updated relationship to .../api/users/{userId}:

• Dogs.
  • Dog.
    • ID : DogB.
    • Private: No. (Updated)

Before I get into work I would greatly appreciate some feedback. Maybe there is other better ways of handling the relationships between resources??

Answer 1

Doing that would violate the principle that REST-Services are idempotent. This means you should be able to send the same operation twice without changing the resource with the second operation.

I'd treat the relation as a separate resource: Create/Update would be PUT ../api/users/{userId}/dogs/{dogId} with Private: Yes/No. Deleting a relation would be handled by DELETE ../api/users/{userId}/dogs/{dogId}.