Definition

EndDefinition

 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. It allows you to define a dedicated profile and user to the API use.  See the Procedure 

Procedure

Procedure_RESTAPIUser

EndProcedure_RESTAPIUser

API References

Access to REST methods

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 methods

Assets

Note: The Assets term includes 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}

   Links of an asset

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

   Catalogs

• View a list of entries of one of the asset catalog  :  GET  /catalog-assets
• View an entry of one of the asset catalog  :  GET  /catalog-assets/{catalog_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}

Tickets

Note: The Tickets term includes incidents, service requests, change requests, investment requests, problems, events.

• View a list of tickets  :  GET   /requests
• View a ticket  :  GET   /requests/{rfc_number}

• View the justification (comment) of a ticket  :  GET   /requests/{rfc_number}/comment
• View the list of the URL of documents attached to a ticket  :  GET   /requests/{rfc_number}/documents

• Create a ticket  :  POST   /requests
• Create a task for a ticket  :  POST   /requests/{rfc_number}/tasks
• Upload and attach a document to a ticket  :  POST   /requests/{rfc_number}/documents
• Update a ticket  :  PUT   /requests/{rfc_number}
• Close a ticket  :  PUT   /requests/{rfc_number}
• Suspend a ticket  :  PUT   /requests/{rfc_number}
• Reopen a ticket  :  PUT   /requests/{rfc_number}
• Finish an action attached to a ticket  :  PUT   /actions/{rfc_number}

   Catalogs

• View a list of entries of one of the ticket catalog  :  GET  /catalog-requests
• View an entry of one of the ticket catalog  :  GET  /catalog-requests/{catalog_id}

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

   Problems

• See a list of problems  :  GET   /problems
• See a problem  :  GET   /problems/{rfc_number}
• See a list of problems attached to a ticket  :  GET   /requests/{rfc_number}/problems
• See a list of tickets attached to a problem  :  GET   /problems/{known_problems_id}/requests

Known errors

• See a list of known errors  :  GET   /knownerrors
• See a known error  :  GET   /knownerrors/{known_problems_id}

Actions

• View a list of actions  :  GET  /actions

• Update an action  :  PUT   /actions/{action_id}
• Finish an action attached to a ticket  :  PUT   /actions/{rfc_number}

Departments / Locations

   Departments

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

• Create a department  :  POST   /departments
• Update a department  :  PUT   /departments/{department_id}

   Locations

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

• Create a location  :  POST   /locations
• Update a location  :  PUT   /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 that have an impact on a CI  :  GET  /configuration-items/{ci_id}/item-links/impacting
• View the list of the links impacted by a CI  :  GET  /configuration-items/{ci_id}/item-links/impacted

• Create a CI  :  POST   /assets
• Update a CI  :  PUT   /assets/{asset_id}

   Links of a CI

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

External tables (E_ tables)

• See a list of records of an external table  :  GET  /E_TABLE

• Create a record in an external table  :  POST  /E_TABLE
• Update a record in an external table  :  PUT  /E_TABLE/{e_table_id}
• Delete a record in an external table  :  DELETE  /E_TABLE/{e_table_id}

Others

• Execute an internal query  :  GET   /internalqueries

HTTP status codes

StatusHeader

EndStatusHeader

Status200

EndStatus200

Status201

EndStatus201

Status204

EndStatus204

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, rfc_number not found.
	{  "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)"  }  }