Home page of Polar Portal | Home | polarsoftware.com
Edit this Topic Edit this Topic
Recent Changes Topics Recent Changes Topics
Show Changes on this Topic Show Changes on this Topic
Find References to this Topic Find References to this Topic
Rename this Topic Rename this Topic
Lost and Found Topics Lost and Found Topics
Print Print
Subscriptions Subscriptions
Upload a file Upload a file

History

11/16/2010 2:09:07 PM
-78.0.250.121
List all versions List all versions

Recent Topics

URIResourcesHTTPMethods

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

URI Resources and HTTP Methods in Polar Help Desk 5 RESTful Web API
.

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

Teams POST GET PUT DELETE POST GET PUT DELETE
/teams o Get: list of Teams
/teams/deleted o Get: list od deleted Teams
/team/{ID} o o o Get: this Team Save: this Team Delete: this Team
/team/{ID}/deleted o o Get: this deleted Team Undelete: this Team
/team/template/{ID} o o Create: new Team using this Team Template Get: this Team Template
/teamtemplate o o Create: new Team Template Get: empty Team Template
/teamtemplates o Get: list of Team Templates
/teamtemplates/deleted o Get: list of deleted Team Templates
/teamtemplate/{ID} o o o Get: this Team Template Save: this Team Template Delete: this Team Template
/teamtemplate/{ID}/deleted o o Get: this Team Template Undelete: this Team Template

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

Incidents by Team POST GET PUT DELETE POST GET PUT DELETE
/incidents/team/{TeamID} o Get: list of Incidents of this Team
/incidents/team/{TeamID}/deleted o Get: deleted Incident of this Team
/incident/{ID}/team/{TeamID} o o o Get: this Incident of this Team Save: this Incident Delete: this Incident
/incident/{ID}/team/{TeamID}/deleted o o Get: this Incident of this Team Undelete: this Incident

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

Filters POST GET PUT DELETE POST GET PUT DELETE
/filters o Get: list of Filters
/filter o o Create: new Filter Get: empty JSON (API)
/filter/{ID} o o o Get: this Filter Save: this Filter Delete: this Filter
/filter/iperson/{MyID} o o Create: new Filter Get: empty JSON (API)
/filters/iperson/{MyID} o Get: list of Filters I created (if my ID matches ID in URI)
/filter/{ID}/iperson/{MyID} o o o Get: this Filter I created (if my ID matches ID in URI) Save: this Filter I created (if my ID matches ID in URI) Delete: this Filter I created (if my ID matches ID in URI)

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.

URI Template HTTP Methods Explanation of HTTP Method on URI Instance
POST GET PUT DELETE POST GET PUT DELETE
Login
/login o o o Login: sends request to login Login Screen Logout
Incidents POST GET PUT DELETE POST GET PUT DELETE
/incidents o Get: list of Incidents
/incidents/deleted o Get: list of deleted Incidents
/incident/{ID} o o o Get: this Incident Save: this Incident Delete: this Incident
/incident/{ID}/deleted o o Get: this deleted Incident Undelete: this Incident
/incident/template/{ID} o o Create: new Incident using this Incident Template Get: this Incident Template
/incident/template/{ID}/email/{EmailID} o o Create: new Incident from this Email using this Incident Template Get: This Incident Template including this Email
POST GET PUT DELETE POST GET PUT DELETE
/incidents/team/{TeamID} o Get: list of Incidents of this Team
/incidents/account/{AccountID} o Get: list of deleted Incidents of this Account
/incidents/team/{TeamID}/deleted o Get: deleted Incident of this Team
/incidents/account/{AccountID}/deleted o Get: deleted Incidents of this Account
/incident/{ID}/team/{TeamID} o o o Get: this Incident of this Team Save: this Incident Delete: this Incident
/incident/{ID}/account/{AccountID} o o o Get: this Incident of this Account Save: this Incident Delete: this Incident
/incident/{ID}/team/{TeamID}/deleted o o Get: this Incident of this Team Save: this Incident Delete: this Incident
/incident/{ID}/account/{AccountID}/deleted o o Get: this Incident of this Account Undelete: this Incident
POST GET PUT DELETE POST GET PUT DELETE
/incidenthistories o Get: list of all Histories of all Incidents
/incidenthistories/deleted o Get: list of all Histories of all Incidents
/incidenthistories/team/{TeamID} o Get: list of all Histories of Incidents of this Team
/incidenthistories/team/{TeamID}/deleted o Get: list of all deleted Histories of all Incidents of this Team
/incidenthistory/{ID}/team/{TeamID} o Get: this Incident History of this Team
/incidenthistory/{ID}/team/{TeamID}/deleted o Get: this deleted Incident History of this Team
/incidenthistory/{ID} o Get: this Incident History
/incidenthistory/{ID}/deleted o Get: this deleted Incident History
POST GET PUT DELETE POST GET PUT DELETE
/incidenttemplates o Get: list of Incident Templates
/incidenttemplates/deleted o Get: list of deleted Incident Templates
/incidenttemplate/{ID} o o o Get: this Incident Template Save: this Incident Template Delete: this Incident Template
/incidenttemplate/{ID}/deleted o o Undelete: this Incident Template
/incidenttemplate o o Create: creates new Incident Template Get: empty Incident Template
Incidents for limited viewing POST GET PUT DELETE POST GET PUT DELETE
/incidentcontacts o Get: list of Incidents (limited view)
/incidentcontacts/deleted o Get: list of deleted Incidents (limited view)
/incidentcontact/{ID} o o o Get: this Incident (limited view) Save: this Incident Delete: this Incident
/incidentcontacts/contact/iperson/{MyID} o o Get: all Incidents reported by me (logged in contact)
/incidentcontact/{ID}/contact/iperson/{MyID} o o o Get: this Incident (if reported by me and in limited view) Save: this Incident Delete: this Incident
/incidentcontact/{ID}/deleted o o Get: this deleted Incident (limited view) Undelete: this Incident
POST GET PUT DELETE POST GET PUT DELETE
/incidentcontacts/account/{AccountID} o o
/incidentcontacts/account/{AccountID}/deleted o o
/incidentcontact/{ID}/account/{AccountID} o o o
/incidentcontact/{ID}/account/{AccountID}/deleted o o
/incidentcontact/template/{ID} o o
Teams POST GET PUT DELETE POST GET PUT DELETE
/teams o Get: list of Teams
/teams/deleted o Get: list of deleted Teams
/team/{ID} o o o Get: this Team Save: this Team Delete: this Team
/team/{ID}/deleted o o
/team/template/{ID} o o
/teamtemplate o o
/teamtemplates o
/teamtemplates/deleted o
/teamtemplate/{ID} o o o
/teamtemplate/{ID}/deleted o o
Accounts POST GET PUT DELETE POST GET PUT DELETE
/accounts o
/accounts/deleted o
/account/{ID} o o o
/account/{ID}/deleted o o
/account/template/{ID} o o
/accounttemplate o o
/accounttemplates o
/accounttemplates/deleted o
/accounttemplate/{ID} o o o
/accounttemplate/{ID}/deleted o o o ???
Workorders POST GET PUT DELETE POST GET PUT DELETE
/workorders o
/workorders/deleted o
/workorder/{ID} o o o
/workorder/{ID}/deleted o o
/workorder/template/{ID} o o
/workorder/{ID}/history o
/workorders/team/{TeamID} o
/workorders/team/{TeamID}/deleted o
/workorder/{ID}/team/{TeamID} o o o
/workorder/{ID}/team/{TeamID}/deleted o
POST GET PUT DELETE POST GET PUT DELETE
/workordertemplates o
/workordertemplates/deleted o
/workordertemplate o o
/workordertemplate/{ID} o o o
/workordertemplate/{ID}/deleted o o
POST GET PUT DELETE POST GET PUT DELETE
/workorderhistories o
/workorderhistories/deleted o
/workorderhistories/team/{TeamID} o
/workorderhistories/team/{TeamID}/deleted o
/workorderhistory/{ID} o
/workorderhistory/{ID}/deleted o
/workorderhistory/{ID}/team/{TeamID} o
/workorderhistory/{ID}/team/{TeamID}/deleted o
Contacts POST GET PUT DELETE POST GET PUT DELETE
/contacts o
/contacts/deleted o
/contact/{ID} o o o
/contact/{ID}/view/{ViewID}/iperson/{MyID} o o
/contact/{ID}/deleted o o
/contact/template/{ID} o o
/contacts/account/{AccountID} o o o
/contacts/account/{AccountID}/deleted o o o
/contact/{ContactID}/account/{AccountID} o o o
/contact/{ContactID}/account/{AccountID}/deleted o o
Person Preferences POST GET PUT DELETE POST GET PUT DELETE
/personpreference o o
/personpreference/{ID} o o o
/personpreference/{ID}/iperson/{MyID} o o
/personpreference/iperson/{MyID} o
/personpreferences o
Documents and Namespaces POST GET PUT DELETE POST GET PUT DELETE
/documenttemplates o
/documenttemplates/deleted o
/documenttemplate o o
/documenttemplate/{ID} o o o
/documenttemplate/{ID}/deleted o o
POST GET PUT DELETE POST GET PUT DELETE
/documents o
/documents/deleted o
/documents/namespace/{NamespaceID} o
/documents/namespace/{NamespaceID}/deleted o
/document/namespace/{NamespaceID} o
/document/{DocumentID}/namespace/{NamespaceID} o o
/document/{DocumentID}/namespace/{NamespaceID}/deleted o o
/documenthistory/{ID}/document/{DocumentID}/namespace/{NamespaceID} o o
/documenthistories/document/{DocumentID}/namespace/{NamespaceID} o
POST GET PUT DELETE POST GET PUT DELETE
/namespace o o
/namespace/{NamespaceID} o o o
/namespace/{NamespaceID}/deleted o o
/namespaces o
/namespaces/deleted o
/namespacehistory/{ID}/namespace/{NamespaceID} o
/namespacehistories/namespace/{NamespaceID} o
POST GET PUT DELETE POST GET PUT DELETE
/documentedit/namespace/{NamespaceID}/template/{TemplateID} o o
/documentedit/{DocumentID}/namespace/{NamespaceID} o o o
/documentedit/{DocumentID}/namespace/{NamespaceID}/deleted o o
Reports POST GET PUT DELETE POST GET PUT DELETE
/reports o Get: list of all Reports
/report/{ReportName} o o Get: this Report Delete: this Report
/reportedit o o Create: new Report Get: empty resource (API)
/reportedits o Get: list of editable Reports
/reportedit/{ReportName} o o o Get: this Report for editing Save: this edited Report Delete: this Report
/reportedits/deleted o Get: list of deleted Reports
/reportedit/{ReportName}/deleted o o Get: this deleted Report Undelete: this Report
/reportedithistory/{ID} o Get: this History of some Report
/reportedithistories o Get: all Histories of all Reports
Users POST GET PUT DELETE POST GET PUT DELETE
/users o
/users/deleted o
/user/{ID} o o o
/user/{ID}/deleted o o
/user/template/{ID} o o
/user/{ID}/view/{ViewID}/iperson/{MyID} o o
User and Contact Templates POST GET PUT DELETE POST GET PUT DELETE
/usertemplates o Get: list of User Templates
/usertemplates/deleted o Get: list of deleted User Templates
/usertemplate o o Create: new User Template Get: empty User Template
/usertemplate/{ID} o o o Get: this User Template Save: this User Template Delete: this User Template
/usertemplate/{ID}/deleted o o Get: this deleted User Template Undelete: this User Template
/contacttemplates o Get: list of Contact Templates
/contacttemplates/deleted o
/contacttemplate o o
/contacttemplate/{ID} o o o
/contacttemplate/{ID}/deleted o o
Filters POST GET PUT DELETE POST GET PUT DELETE
/filters o Get: list of all Filters
/filter o o Create: new Filter Get: empty resource (API)
/filter/{ID} o o o Get: this Filter Save: this Filter Delete: this Filter
/filter/iperson/{MyID} o o Create: new Filter (API) Get: empty resource (API)
/filters/iperson/{MyID} o Get: list of Filters I created
/filter/{ID}/iperson/{MyID} o o o Get: this Filter I created Save: this Filter I created Delete: this Filter I created
Roles POST GET PUT DELETE POST GET PUT DELETE
/roles o
/roles/deleted o
/role o o
/role/{ID} o o o
/role/{ID}/deleted o o
Email Notifications POST GET PUT DELETE POST GET PUT DELETE
/emailnotifications o
/emailnotifications/deleted o
/emailnotification/{ID}/deleted o o
/emailnotification o o
/emailnotification/{ID} o o o
Services, Service Levels and Service Level Agreements POST GET PUT DELETE POST GET PUT DELETE
/services o
/services/deleted o
/service/{ID}/deleted o o
/service o o
/service/{ID} o o o
/servicelevels o
/servicelevels/deleted o
/servicelevel/{ID}/deleted o o
/servicelevel o o
/servicelevel/{ID} o o o
/servicelevelagreements o
/servicelevelagreements/deleted o
/servicelevelagreement/{ID}/deleted o o
/servicelevelagreement o o
/servicelevelagreement/{ID} o o o
Origins POST GET PUT DELETE POST GET PUT DELETE
/origins o Get: list of Origins
/origins/deleted o
/origin o o
/origin/{ID} o o o
/origin/{ID}/deleted o o
Emails and Email Templates POST GET PUT DELETE POST GET PUT DELETE
/emailtemplates o Get: list of Email Templates
/emailtemplates/deleted o Get: list of deleted Email Templates
/emailtemplate o o Create: new Email Template Get: empty Email Template
/emailtemplate/{ID} o o o Get: this Email Template Save: this Email Template Delete: this Email Template
/emailtemplate/{ID}/deleted o o Get: this deleted Email Template Undelete: this Email Template
/emails o Get: list of downloaded Emails
/emails/deleted o Get: list of deleted Emails
/email/{ID} o o Get: this Email Delete: this Email
/email/{ID}/deleted o o Get: this deleted Email Undelete: this Email
Categories and Closure Classifications POST GET PUT DELETE POST GET PUT DELETE
/categories o Get: list of Categories
/categories/deleted o
/category o o
/category/{ID} o o o
/category/{ID}/deleted o o
/closureclassifications o Get: list of Closure Clasifications
/closureclassifications/deleted o
/closureclassification o o
/closureclassification/{ID} o o o
/closureclassification/{ID}/deleted o o
License POST GET PUT DELETE POST GET PUT DELETE
/license o o Get: list of license keys and named users Save: license key and named users
Active Directory Import POST GET PUT DELETE POST GET PUT DELETE
/activedirectoryimportschemas o Get: list of AD Import Schemas
/activedirectoryimportschema o o Create: new AD Import Schema Get: this AD Import Schema
/activedirectoryimportschema/{ID} o o o o Import Users: using this AD Import Schema Get: this AD Import Schema Save: this AD Import Schema Delete: this AD Import Schema
Attachments POST GET PUT DELETE POST GET PUT DELETE
/attachment o Upload: new Attachment
/attachment/{GUID} o o Get: this Attachment Delete: this Attachment
Email Accounts POST GET PUT DELETE POST GET PUT DELETE
/emailaccounts o Get: list of Email Accounts
/emailaccounts/deleted o Get: list of deleted Email Accounts
/emailaccount o o Create: new Email Account Get: empty Email Account form
/emailaccount/{ID} o o o Get: this Email Account Save: this Email Account Delete: this Email Account
/emailaccount/{ID}/deleted o o Get: this deleted Email Account Undelete: this Email Account
Scheduler and Settings POST GET PUT DELETE POST GET PUT DELETE
/scheduler o o Get: Scheduler form Start Scheduler
/settings o o Get: Settings Save: Settings
Password and Registration POST GET PUT DELETE POST GET PUT DELETE
/resetpassword o Get: empty resource (API)
/resetpassword/{GUID} o o Get: Reset Password form Reset Password
/forgottenpassword o o
/registercontact/{ID} o o Create: new Contact using this Template Get: this Contact Template
Languages POST GET PUT DELETE POST GET PUT DELETE
/languages o Get: list of Languages
/languages/deleted o Get: list of deleted Languages
/language o o Create: new Language Get: empty Language form
/language/{LanguageName} o o o Get: this Language Save: this Language Delete: this Language
/language/{LanguageName}/deleted o o Get: this deleted Language Undelete: this deleted Language
/languageembedded o Get: embedded english language
/languageconverter o Convert language xmp/csv/JSON (API)
Import Contacts, Upload Files, Logs POST GET PUT DELETE POST GET PUT DELETE
/importcontactsfromfile o o Post: parse CSV data and create users Get: empty import form
/uploadfiles o Upload: new file
/logs o Get: list of Logs
/log/{LogName} o Get: this Log txt
POST GET PUT DELETE POST GET PUT DELETE

Resources:

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

.......