REST (Representational State Transfer) is an architectural style for distributed hypermedia systems. It is 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 / PATCH (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.

• The methods (operations) PUT and PATCH which allow to modify a specified resource are equivalent.

• The methods which allow to obtain a specified resource or to modify a specified resource use a mandatory parameter that corresponds to a field of the  database for which we can guarantee the uniqueness.
        asset_id parameter for the following methods:
  • GET /assets/{asset_id}  :  View an asset method
  • PUT /assets/{asset_id}  or  PATCH /assets/{asset_id}  :  Update an asset method

• When you wish to obtain a specified resource or to modify a specified resource for which the third-party system does not know the value of the field used as parameter, you should use the method to obtain a list by applying the desired search/filter options on the fields of the database. You can then use the link URL (HREF) provided which contains the unique identifier of each resource.
        To obtain a specified access:
  • You should use the View a list of assets method (GET /assets) with the possible search/filter options on the fields asset_id, employee_id, location_id, department_id.
  • Then you can use the link URL: "HREF": "https://{your_server}/api/v1/{your_account}/assets/27590" to access the asset of which the identifier is 27590.

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

Best Practice

• To run your tests, you shoud use:
  • The HTTP request library providing by . It contains a set of examples which may help you understand and use the  REST API and run tests in your specific  environment if required.
  • Postman (extension of Chrome). It is an excellent third-party tool for mechanizing API tests; particularly REST API. 

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 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:

         Requests examples

• You can use the wildcard character *, by replacing the character : by the character ~ (equivalent to the LIKE SQL instruction).
  The syntax to be used is the following one:

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.

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 (equipment / licenses / contracts)

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

• View a list of asset catalog entries  :  GET  /catalog-assets
• View an asset catalog entry  :  GET  /catalog-assets/{catalog_id}

• View the list of links of an asset  :  GET  /assets/{asset_id}/asset-links
• View an asset link  :  GET  /assets/{asset_id}/asset-links/{parent_asset_id}
• Create an asset link  :  POST  /assets/{asset_id}/asset-links/{parent_asset_id}
• Update an asset link  :  PUT  /assets/{asset_id}/asset-links/{parent_asset_id}
• Delete an asset link  :  DELETE  /assets/{asset_id}/asset-links/{parent_asset_id}

Manufacturers

• View a list of manufacturers  :  GET  /manufacturers
• View a manufacturer  :  GET  /manufacturers/{manufacturer_id}

Employees

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

SLAs

• View a list of SLAs  :  GET  /slas
• View a SLA  :  GET  /slas/{sla_id}

Incidents / Requests

• View a list of incident-request catalog entries  :  GET  /catalog-requests
• View an incident-request catalog entry  :  GET  /catalog-requests/{catalog_id}

•  View the list of paths of incident-request catalog entries  :  GET  /catalog-requests-paths
•  View the list of paths of an incident/request catalog entry  :  GET /catalog-requests-paths/{catalog_id}

• View a list of incidents/requests  :  GET   /requests
• View an incident/request  :  GET   /requests/{rfc_number}

• View the justification (comment) of an incident/request  :  GET   /requests/{rfc_number}/comment
• View 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

Problems / Known errors

• View a list of problems and known errors  :  GET  /known-problems
• View a problem or known error  :  GET  /known-problems/{known-problem_id}

Departments / Locations

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

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

Configuration items (CIs)

• View a list of CIs  :  GET  /configuration-items
• View a CI  :  GET  /configuration-items/{ci_id}

• View the list of the links of a CI  :  GET  /configuration-items/{ci_id}/item-links
• View a CI link  :  GET  /configuration-items/{parent_ci_id}/item-links/{child_ci_id}
• Create a CI link  :  POST  /configuration-items/{parent_ci_id}/item-links/{child_ci_id}
• Update a CI link  :  PUT  /configuration-items/{parent_ci_id}/item-links/{child_ci_id}
• Delete a CI link  :  DELETE  /configuration-items/{parent_ci_id}/item-links/{child_ci_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 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 database fields.
	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 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)"  }  }