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:

 can be:

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

    Component of creation or suspension of an incident in

  In this case, the third-party application (e.g. another Service Desk application) must call the  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  was active.

• Consumer using external REST web services.

    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  REST API exchange format is JSON.

• The  API REST allows to manage the following resources.

• 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   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.

• Results (JSON format) are returned in the language of the user for which the account is used to access to the  REST API.

• Postman (extension of Chrome) is an excellent third-party tool for mechanizing API tests; particularly REST API. 

•  provides a HTTP request library containing a set of examples which may help you understand and use the  REST API and run tests in your specific  environment if required.

Licensing and security system

All operations carried out with  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  REST API by standard users, the REST API field has been added to profile management.
         

Search/filter options

By date

Note: The expected date format is that employed by the logged-in  REST API user.

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

• You can use specific intervals.

By field

In the HTTP requests, you can do a search/filter on one or several fields of the  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:

• (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

API References

Access to REST functions

Access is via a URL of format:  

• {your_server}: server URL
             https://your_company.easyvista.com 

• {your_account}: Account used
             50004: Production base; 50005: Sandbox base

• {resource_name}: Name of the resource called
             requests ; assets ; employees
   

List of the REST API functionalities

  Assets

• See a list of assets:  GET   /assets
• See an asset:  GET   /assets/{asset_id}
• Create an asset:  POST   /assets
• Update an asset:  PUT   /assets/{asset_id}
   

  Employees

• See a list of employees:  GET   /employees
• See an employee:  GET   /employees/{employee_id}
• Create an employee:  POST   /employees
• Update an employee:  PUT   /employees/{employee_id}
   

  Incidents / Requests

• See a list of incidents/requests:  GET   /requests
• See an incident/request:  GET   /requests/{rfc_number}
• See the justification (comment) of an incident/request  : GET   /requests/{rfc_number}/comment
• See the list of the URL of documents attached to an incident/request:  GET   /requests/documents/{rfc_number}
• Create an incident/request:  POST   /requests
• Upload and attach a document to an incident/request:  POST   /requests/{rfc_number}/documents
•  Update an incident/request:  PUT   /requests/{rfc_number}
•  Close an incident/request:  PUT   /requests/{rfc_number}
• Suspend an incident/request:  PUT   /requests/{rfc_number}
• Reopen an incident/request:  PUT   /requests/{rfc_number}
• Finish an action attached to an incident/request:  PUT   /actions/{rfc_number}
• Create a task for an incident/request:  POST   /requests/{rfc_number}/tasks
   

   Departments

•  See a list of departments:  GET   /departments
•  See a department:  GET   /departments/{department_id}
   

   Locations

•  See a list of locations:  GET   /locations
•  See a location:  GET   /locations/{location_id}
   

  Others

• Execute an internal query:  GET   /internalqueries

HTTP status codes

StatusHeader

EndStatusHeader

Status200

EndStatus200

Status201

EndStatus201

Status400

400	Bad Request	Request formulated incorrectly and cannot be executed correctly.
	{  "error": "Nothing to update (check fieldnames)" }

EndStatus400

Status401

401	Unauthorized	Authentication process for accessing the resource is incorrect: Login/Password incorrect, Invalid session, Incorrect account.
	{  "error": "Invalid Login / Password" }

EndStatus401

Status403

EndStatus403

Status404

404	Not Found	Resource not found: Incorrect URI, Missing resource, Incorrect communication with the server.
	{  "error": "Resource not found" }

EndStatus404

Status405

405	Method not allowed	Request method not authorized: not supported or not appropriate for the resource.
	{  "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 REST API is JSON.

EndStatus406

Status409

EndStatus409

Status413

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.
	{  "error": "An error occured. A text message is returned in the body." }

EndStatus500

Status503

EndStatus503

ConventionsAPI

REST API Conventions

Convention	Meaning
Orange	Parameters used in an HTTP request string (URL) which do not correspond to database fields.
	Method See 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 database fields.
	Method See 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 database fields; they allow the value of a database field to be assigned or modified.
	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 database fields.
	Method Reopen an incident/request {  "restarted": {  "comment": "string (required)"  }  }