Web Services REST


REST (Representational State Transfer) is an architectural style for distributed hypermedia systems based on the HTTP protocol for accessing resources (thanks to their unique URI) using various operations supported natively by the protocol: GET (read), POST (write), PUT (modify), DELETE (delete)... 

  Operating principle:

1. A consumer makes an application via a request to a REST API with a web services provider.
2. The REST web service carries out the request and returns a response to the consumer in the form of a data stream (usually JSON format, this format having become established over the years).
3. The consumer uses the response as part of an application he/she has developed.

Product name - ev itsm.png can be:

  • Supplier of REST web services thanks to its REST API: the services offered are well-defined business functions.

    Example documentation icon EN.png  Component of creation or suspension of an incident in Product name - ev itsm.png

    In this case, the third-party application (e.g. another Service Desk application) must call the Product name - ev itsm.png REST web service sending the values expected by the web service parameters (e.g. the number of the incident to suspend); processing is then carried out as if Product name - ev itsm.png was active.
  • Consumer using external REST web services.

    Example documentation icon EN.png  Use, during a workflow step, of an external component for resetting passwords

    In this case, the external REST web service must be declared and configured in the Administration > REST > Services menu before it can be accessed from a step in the process (via a REST action).

Notes

  • The Product name - ev itsm.png REST API exchange format is JSON.
  • The Product name - ev itsm.png API REST allows to manage the following resources.
Resource JSON Object SQL Table
requests request SD_REQUEST
assets asset AM_ASSET
employees employee

alias: recipient; requestor ( * )

AM_EMPLOYEE
departments department AM_DEPARTMENT
locations location AM_LOCATION
status status SD_STATUS

( * ) The employee JSON object has 2 alias which are used for the requests resource to manage the case of the foreign keys submitted_by and recipient_id of the SD_REQUEST table.

  • For the methods (operations) which allow to obtain a specified resource (ex.: GET /assets/{asset_id}) or to modify a specified resource (ex.: PUT /assets/{asset_id}), the mandatory parameter to be used (ex.: {asset_id}) corresponds to a field of the  Product name - ev itsm.png database for which we can guarantee the uniqueness.
  • When you wish to obtain (ex.: GET /assets/{asset_id}) or to modify (ex.: PUT /assets/{asset_id}) a specified resource for which the third-party system does not know the value of the field used as parameter (ex.: asset_id, employee_id, location_id, department_id), use the method to obtain a list with the search/filter option on the fields of the database. You can then use the link URL (HREF) provided which contains the unique identifier of a resource.

Example documentation icon FR.png "HREF": "https://{your_server}/api/v1/{your_account}/assets/27590"

  • Results (JSON format) are returned in the language of the user for which the account is used to access to the Product name - ev itsm.png REST API.
  • Postman (extension of Chrome) is an excellent third-party tool for mechanizing API tests; particularly REST API. 
  • Logo - EasyVista.png provides a HTTP request library containing a set of examples which may help you understand and use the Product name - ev itsm.png REST API and run tests in your specific Product name - ev itsm.png environment if required.

Licensing and security system

All operations carried out with Product name - ev itsm.png REST API require a login in order to access a specific domain. Each time a call is made to the API, user access is recorded.

For security reasons and to prevent unwanted use of the Product name - ev itsm.png REST API by standard users, the REST API field has been added to profile management.
         EVSM REST API - Profile.png

Best Practice icon.png  Create a dedicated user (via the list of Employees), authorized to carry out REST requests.
         EVSM REST API - Employee REST.png

Search/filter options

By date

Note: The expected date format is that employed by the logged-in Product name - ev itsm.png REST API user.

  • Filtering by date can be carried out in all Date fields.
  • Date intervals are inclusive.
  • You can use predefined intervals.

Example documentation icon EN.png

search=SUBMIT_DATE_UT:LAST_WEEK
search=SUBMIT_DATE_UT:3daysbefore

The possible values are:
THIS_YEAR
THIS_MONTH   
THIS_WEEK
THIS_DAY / TODAY
LAST_YEAR
LAST_MONTH
LAST_WEEK
FIRST_QUARTER / Q1
SECOND_QUARTER / Q2
THIRD_QUARTER / Q3
FOURTH_QUARTER / LAST_QUARTER/ Q4
NEXT_DAY / TOMORROW
NEXT_WEEK
NEXT_MONTH
NEXT_YEAR
DAYSBEFORE
DAYSAFTER

  • You can use specific intervals.

Example documentation icon EN.png  From 05/10/2016 to 06/10/2016

search=SUBMIT_DATE_UT:(10/05/2016;10/06/2016) 

By field

In the HTTP requests, you can do a search/filter on one or several fields of the Product name - ev itsm.png database by using the names of corresponding objects. However, you cannot use only once the same object in the same request (the union is not possible).

The syntax to be used is the following one:

search={(prefix_object_name_1.)object_name_1}:{object_name_value_1}(,{(prefix_object_name_2.)object_name_2}:{object_name_value_2})
  • (prefix_object_name_x.): Prefix to be only indicated when the wished object is contained in another object.
  • object_name_x: Name of the used object. Mandatory parameter.
  • object_name_value_x: Value of the used object. Mandatory parameter.
     

Requests examples

Correct
/employees?search=last_name:"Morley, Gaby"

/assets?search=asset_tag:"1012D"
/assets?search=employee.last_name:"Taverner, David"
/assets?search=department.department_en:"Finance"

/requests?search=department.department_en:"Industry"
/requests?search=status.status_en:"Closed"
/requests?search=status.status_en:"In Progress",submit_date_ut:this_week&sort=recipient.last_name+asc
/requests?search=recipient.last_name:"Morley, Gaby"
/requests?search=requestor.last_name:"Morley, Gaby"
/requests?search=recipient.last_name:"Morley, frédérique",status.status_en:"In Progress"
/requests?search=recipient.e_mail:fpachelbel@evtry.com,status.status_en:"Escalated"
/requests?search=recipient.e_mail:adam@evtry.com,status.status_en:"In Progress",submit_date_ut:today
/requests?search=recipient.last_name:"Adam, George",status.status_en:"Closed",submit_date_ut:this_year
/requests?search=recipient.last_name:"Adam, George",status.status_en:"In Progress",submit_date_ut:this_week&sort=submit_date_ut+asc
Incorrect
/requests?search=recipient.e_mail:adam@evtry.com,morley@evtry.com
/requests?search=recipient.e_mail:adam@evtry.com,recipient.e_mail:morley@evtry.com
/requests?search=recipient.e_mail:adam@evtry.com&morley@evtry.com
/requests?search=recipient.e_mail:adam@evtry.com&recipient.e_mail:morley@evtry.com

API References

Access to REST functions

Access is via a URL of format:  

https://{your_server}/api/v1/{your_account}/{resource_name}
  • {your_server}: server URL
             Example documentation icon EN.png  https://your_company.easyvista.com 
  • {your_account}: Account Product name - ev itsm.png used
             Example documentation icon EN.png  50004: Production base; 50005: Sandbox base
  • {resource_name}: Name of the resource called
             Example documentation icon EN.png  requests ; assets ; employees
     

List of the REST API functionalities

  Assets

  Employees

  Incidents / Requests

   Departments

  • New small wiki button.png View a list of departments:  GET   /departments
  • New small wiki button.png View a department:  GET   /departments/{department_id}
     

   Locations

  • New small wiki button.png View a list of locations:  GET   /locations
  • New small wiki button.png View a location:  GET   /locations/{location_id}
     

  Others

HTTP status codes

StatusHeader
Code Error Description
EndStatusHeader
Status200
200 OK (Success) Request processed successfully.
EndStatus200
Status201
201 Created Request processed successfully and an item created.
EndStatus201
Status400
400 Bad Request Request formulated incorrectly and cannot be executed correctly.
Example documentation icon EN.png
{
 "error": "Nothing to update (check fieldnames)"
}
EndStatus400
Status401
401 Unauthorized Authentication process for accessing the resource is incorrect: Login/Password incorrect, Invalid session, Incorrect Product name - ev itsm.png account.
Example documentation icon EN.png
{
 "error": "Invalid Login / Password"
}
EndStatus401
Status403
403 Forbidden Server refused to execute the request. Unlike error 401, authentication is accepted but access rights do not authorize the client to access the resource: The user does not have the REST API parameter enabled in their profile.
EndStatus403
Status404
404 Not Found Resource not found: Incorrect URI, Missing resource, Incorrect communication with the server.
Example documentation icon EN.png
{
 "error": "Resource not found"
}
EndStatus404
Status405
405 Method not allowed Request method not authorized: not supported or not appropriate for the resource.
Example documentation icon EN.png
{
 "error": "Invalid input parameter"
}
EndStatus405
Status406
406 Not acceptable Resource not available in a format complying with the Accept headers of the request. Note: The exchange format of the Product name - ev itsm.png REST API is JSON.
EndStatus406
Status409
409 Conflict Unable to process request in the current state. Records cannot be modified or deleted.
EndStatus409
Status413
413 Request entity too large Processing abandoned because the request was too large.
EndStatus413
Status500
500 Internal Server Error Generic error message displayed when an unexpected condition is encountered and there is no appropriate message which is more specific.
Example documentation icon EN.png
{
 "error": "An error occured. A text message is returned in the body."
}
EndStatus500
Status503
503 Service unavailable Service temporarily unavailable or under maintenance. The request cannot be processed.
EndStatus503


ConventionsAPI

REST API Conventions

Convention Meaning
Orange Parameters used in an HTTP request string (URL) which do not correspond to Product name - ev itsm.png database fields.
Example documentation icon EN.png   Method View a list of assets
https://{your_server}/api/v1/{your_account}/assets?max_rows=3&fields=asset_tag
Black and Bold Parameters used in the URL of an HTTP request which correspond to Product name - ev itsm.png database fields.
Example documentation icon EN.png   Method View an asset
https://{your_server}/api/v1/{your_account}/assets/{asset_id}
Green Parameters used in the body of an HTTP request which represent JSON object names corresponding to Product name - ev itsm.png database fields; they allow the value of a database field to be assigned or modified.
Example documentation icon EN.png   Method Close an incident/request

{  "closed": {  "end_date": "11/20/2016 12:12:12",  }  }
Parameters used in the body of an HTTP request which represent JSON object names not corresponding to Product name - ev itsm.png database fields.
Example documentation icon EN.png   Method Reopen an incident/request

{  "restarted": {  "comment": "string (required)"  }  }

Tags:
Last modified by Christine Daussac on 2017/10/03 12:31
Created by Administrator XWiki on 2016/11/23 10:15

Shortcuts

Recent Updates

Haven't been here in a while? Here's what changed recently:

-   Product name - ev itsm.png
-   Product name - ev sas.png

Interesting Content

How to Automate Integration
Add a Shortcut to an App
History
Quick Dashboard
Full text search - Stop Words

Powered by XWiki ©, EasyVista 2017