Definition

EndDefinition

Operating principle

Service Manager can be:

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

  example   Component of creation or suspension of an incident in Service Manager

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

• Consumer using external REST web services.

  example   Use of an external component for resetting passwords during a workflow step

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

Notes

• The Service Manager REST API exchange format is JSON.

• The Service Manager REST API 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 Service Manager database for which we can guarantee the uniqueness.
      example   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.
      example   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 Service Manager REST API.

Best Practice

• To run your tests, you shoud use:
  • The HTTP request library providing by EasyVista. It contains a set of examples which may help you understand and use the Service Manager REST API and run tests in your specific Service Manager 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 the Service Manager 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 Service Manager 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_RESTAPIUserProfile

EndProcedure_RESTAPIUserProfile

API References

Access to REST methods

Access is via a URL of format:  

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

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

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

       example 

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}

  Attributes

• View all the attributes of a list of assets  :  GET  /asset-characteristics
• View all the attributes of an asset  :  GET  /asset_characteristics/{asset_id}

• Create a link between an attribute and an asset  :  POST  /assets/{asset_id}/characteristics/{characteristic_id}
• Update an attribute of an asset  :  PUT  /assets/{asset_id}/characteristics/{characteristic_id}

  Catalogs

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

  Links of an asset

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

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

• Create a ticket  :  POST   /requests
• Create a task for a ticket  :  POST   /requests/{rfc_number}/tasks
• 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}

  Catalogs

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

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

  Problems

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

  Documents

• View all the URLs of documents attached to a ticket  :  GET   /requests/{rfc_number}/documents
• Download document  :  GET   /documents/{document_id}
• Attach documents to a ticket  :  POST   /requests/{rfc_number}/documents
• Delete a document  : DELETE  /documents/{document_id}

Questions / Questionnaires

• View a list of questions  :  GET   /questions
• View a list of questions with a response  :  GET   /questions-result
• View a question  :  GET   /questions/{question_id}
• View all the responses to a list of questions of a ticket  :  GET   /questions-result/{request_id}
• View the response to a question of a ticket  :  GET   /questions-result/{request_id}/{question_id}
• Create the response to a question of a ticket  :  POST   /questions-result/{request_id}/{question_id}
• Update the response to a question of a ticket  :  PUT   /questions-result/{request_id}/{question_id}

• View a list of questionnaires  :  GET   /questionnaires
• View a questionnaire  :  GET   /questionnaires/{questionnaire_id}

Problems

• View a list of problems  :  GET   /problems
• View a problem  :  GET   /problems/{rfc_number}

Known errors

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

News

• View a list of news  :  GET   /news
• View a news  :  GET   /news/{document_id}
• Create a news  :  POST   /news
• Update a news  :  PUT   /news/{document_id}

Actions

• View a list of actions  :  GET  /actions

• Create an action for a ticket  :  POST   /requests/{rfc_number}/actions
• Update an action  :  PUT   /actions/{action_id}
• End one or more ongoing actions of 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}

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

  Links of a CI

• View a list of 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}

• View all the links that have an impact on a CI  :  GET  /configuration-items/{ci_id}/item-links/impacting
• View all the links impacted by a CI  :  GET  /configuration-items/{ci_id}/item-links/impacted

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

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

EndStatus400

Status401

EndStatus401

Status403

EndStatus403

Status404

EndStatus404

Status405

EndStatus405

Status406

EndStatus406

Status409

EndStatus409

Status413

EndStatus413

Status500

EndStatus500

Status503

EndStatus503

ConventionsAPI