Abstract

List of URI Templates and HTTP Methods with Explanation of every available HTTP Method on each URI Instance.

Questions and Answers

1. What is the difference between URI Template and URI Instance?
1. URI Template is a blueprint which fits a given set of URI's, eg. /incident/{ID} and URI Instance is instance of that URI Template eg. /incident/4, /incident/5, etc.
2. You use URI Templates to give permission to Client to send requests on URI Instances and get Server to do what it is requesting.
2. Explanation of HTTP Methods
1. POST usually means 'Create new' resource, GET means 'Get' a resource, PUT means 'Save' a resource, and DELETE means 'Delete' a resource.
2. For example, when you are viewing an Incident with ID 4 and click on Delete button, your Client (eg. browser) will send a request 'DELETE /incident/4'. If you have permission to do that, Server will Delete Incident with ID 4.
3. What is the difference between Request for HTTP Method on URI Instance and Permission to HTTP Method on URI Template?
1. Request for 'PUT /incident/4' means that you are trying to Save Incident with ID 4. It is a communication between your Client and the Server.
2. Permission to 'PUT /incident/{ID}' means that you can Save every instance of /incident/{ID} e.g. /incident/4. It is a permission you can have or not have depending on what is checked in Role your Team is in.
4. Can I give a permission to a user to PUT /incident/4 without giving him permission to PUT /incident/{ID} for every ID?
1. Yes, you can. You can give user-defined permissions too. You can find them in the bottom of each Role.

Standard implementation

Usually resources have:

1. group URI with method GET to view list of resources (e.g. /incidents is list of all incidents)
2. individual URI with methods GET, PUT and DELETE to view, save and delete individual resource (e.g. /incident/3)
3. template URI for creating new resources (e.g. /incident/template/4) with method POST to create new resource using this template, and GET to view this template
4. group and individual URI deleted for resources which have been deleted, with methods GET to view the resource and PUT to undelete the resource (e.g. /incidents/deleted and /incident/4/deleted)

Example of standard implementation of group, individual, template and deleted URI

Additionally, some resources have:

1. group and individual URI filtered by some value e.g. /incidents/team/{TeamID} to allow you to give permissions to view incidents of a particular team without giving permissions to view all incidents. For example, Hardware Team /team/3 is in Hardware Team Role. In that Role permissions to GET /incidents/team/3 and GET, PUT and DELETE /incident/{ID}/team/3 are given in user defined permissions and permissions to GET /incidents and GET, PUT and DELETE /incident/{ID} are not given.

Example of standard implementation of URI with added filter by some value

Also, some resources have:

1. authentication part e.g. /filters/iperson/{MyID} to allow you to give permissions to logged in person to view filters that are his/her own without giving him/her permission to view everybody's filters. For example, user with ID 4 has permission to GET /filters/iperson/{MyID}. When Client sends request to GET /filters/iperson/3, Server checks if ID in URI and ID of logged in person is the same, if they are access is granted, if not, access is denied. This user has ID 4 so access will be denied.

Example of standard implementation of URI with authentication part

Role Table with Explanations

In this table, on the left, all URI Templates are listed and all HTTP Methods that are available on each URI Template is marked by "o". This is the same table you see when you are editing a particular Role. On the right you can see explanations of a HTTP Method on instance of that URI Template.

If explanation is not given, standard implementation applies: POST is to create, GET is to view, PUT is to save or undelete, DELETE is to delete.

Resources:

http://en.wikipedia.org/wiki/Representational_State_Transfer