Is single rest 'put' endpoint enough to update a document with nested arrays?
Your API design is ultimately your choice. Personally I prefer to keep things quite shallow, maybe one relationship deep if that. Generally I will have an endpoint per resource.
In terms of your example about the new phone number for existing manager for an existing customer. A general flow using a somewhat shallow api could be:
- Frontend:
- Goto URL site/users/1 (this loads up the basic view for the user).
- API:
- Action: GET
- Url: site/api/v1/users/1
- Desc: SHOW user 1
- Response:
{ id: 1, name: "bob", age: 22 }
- API:
- Action: GET
- Url: site/api/v1/managers?query=user_id=1
- Desc: INDEX all manager for user 1
- Response:
{ [ { id: 55, name: "mana1", phone: 4444 }, { id: 66, name: "mana2", phone: 333 }, .. ] }
- Frontend: List managers as a bunch of forms with some hidden id's
- Frontend: Enter phone number hit save
- API:
- Action: PATCH
- Url: site/api/v1/managers/55
- BODY:
{ phone: 9898 } - Desc: PATCH manager 55 with new phone data
- Response: { ..updated data.. }
I personally really like this for API's:https://github.com/WhiteHouse/api-standards
It's not rest, but its simple, repeatable and usable.