1.2 Resources and Responses

Requests and responses are built around the transfer of representations of resources. A resource is any meaningful entity or concept that may be acted upon. For example, in Filr, folders, files and users are resources.

There are several different logical categories of resources:

  • Object

    • For example, a folder

  • Collection

    • For example, the set of files in a folder

    • Each file by itself is an object resource, but the set of files in a folder is a collection resource that can also be acted upon.

  • Attribute

    • For example, a folder’s parent

REST clients act on these resources using standard HTTP verbs (methods):

  • GET: retrieve the resource from the server

  • POST: create a new resource on the server/modify an existing resource

  • PUT: modify a resource

  • DELETE: delete a resource

Depending on the type of resource, each HTTP method has a different meaning:

  • Folder (object resource)

    • GET: retrieves a representation of the folderl

    • PUT (or perhaps POST): modifies the folder

    • DELETE: deletes the folder

  • Set of files in a particular folder (collection resource)

    • GET: retrieves the list of files

    • POST: add an additional file to the collection (create a new file in the folder)

    • PUT: replace the entire collection with a new list of files

    • DELETE: deletes all files in the folder

  • Folder’s parent (attribute resource)

    • GET: Retrieves the parent of the folder

    • PUT (or perhaps POST): Updates the parent folder attribute (moves the folder to a different location)

      DELETE: Removed the parent folder attribute (in this example, it would not make sense to support the DELETE method, because the parent folder attribute is mandatory)