Entity Pattern

The entity pattern applies to resources that can be read with a GET operation, but can only be changed by PUT and DELETE operations.  For example, consider our image example from before.  We can read the image by doing:

GET http://myserver/myphotos/mywedding.img

We can replace the image by doing:

PUT http://myserver/myphotos/mywedding.img

Note that this operation would succeed regardless if the resource existed before or not, because the photo album resource allows for generic nested resources.

And we can delete the image by doing:

DELETE http://myserver/myphotos/mywedding.img

The entity pattern also applies to resources with sub-structure that are accessible as nested resources.  For example, consider an entry in an address book.  We can retrieve the entry in its entirety by doing a GET operation on it:

GET http://myserver/myaddressbook/johndoe

We can also update individual properties of the entry, because they are exposed as nested resources.  For example, to change the work phone number, we can do a PUT operation on the corresponding resource:

PUT http://myserver/myaddressbook/johndoe/workphone

Note that this operation would succeed regardless if the resource existed before or not, because the contact resource allows for a nested resource of this name.

Similarly, we can remove a property by doing a DELETE operation on its resource:

DELETE http://myserver/myaddressbook/johndoe/homephone

An entity may have nested resources, but these nested resources are either generic, as is the case in our photo album example, or they are predefined, as is the case in our contact example.  In both cases, no algorithm was required to divine what the nested resource's name would be.  Also note that a nested resource of an entity does not have to be an entity too.  A nested resource can be anything it wants or needs to be.

An entity resource has the following pattern: