Service Desk Web Service API Basics

• Query data in your organization.
• Add, update, and delete data.

This article provides information about Web Service API basics and contains the following topics:

Characteristics of API Calls

API calls contain the following characteristics:

• Requests and Responses: Your client application prepares and submits a request to the Service Desk Web Service using the API, the Service Desk Web Service processes the request and returns a response, and the client application handles the response.
• Synchronous: Once the API call is invoked, your client application waits until it receives a response from the service. Asynchronous calls are not supported.
• Committed Automatically Versus Rollback on Error: By default, every operation that writes to a Service Desk object, is committed automatically. This behavior is analogous to the AUTOCOMMIT setting in SQL.
• For create(), update(), and delete() calls that attempt to write to multiple records for an object, the write operation for each record is treated as a separate transaction. For example, when client applications attempt to create two new accounts, they are created using mutually exclusive insert operations that succeed or fail individually, not as a group.  

• Your organization must be enabled for WS API access, and the user attempting to access the WS API must have the "Web Service" license type.
• Whether your configured permissions allow access to the data. Your client application logs in as a user to the Service Desk Web Service. The profile that is associated with the logged-in user grants or denies access to specific objects and fields in your organization.
• When an application logs into the API, all transactions are run as the user who logs in. Therefore, to protect the security of your data, give that user (the logged-in user) only the permissions that are needed to execute all the calls that are made by the application.
• Whether a particular change would compromise the referential integrity of the Service Desk data for your organization.
• Whether a given field in an object can be updated or not. For example, read-only fields cannot be changed in create() or update() calls.
• The API automatically enforces the rules for the custom objects. For example, this behavior affects fields that are configured in the Service Desk user interface to be unique or required.

Web Service Output Data Format Types

CA Cloud Service Management supports the following HTTP protocol standard data types:

• JSON - http://json.org/
• XML - http://en.wikipedia.org/wiki/XML
• JAVA BEAN - http://en.wikipedia.org/wiki/JavaBean

Security

The client applications that access the Service Desk data for your organization are subject to the same security protections that are used in the Service Desk user interface. The client applications must log in using valid credentials for an organization. The server authenticates these credentials and, if valid, permits access to the web service operation.

The Service Desk administrator for the organization controls the availability of various features and views by configuring profiles and assigning users to the features and views. To access the API (to issue calls and receive the call results), users must be granted the "Web Services" license. The client applications can query or update only those objects and fields to which their customer-slice has access using the profile of the logged-in user.

For access using the API or a client, users must either use their security token or provide their login id and password to log in. A security token is an automatically generated key from Service Desk.

Error Handling

The API calls return error data that your client application can use to identify and resolve runtime errors. When an error occurs during the invocation of most API calls, the API provides the following types of error handling:

• For errors resulting from badly formed messages, failed authentication, or similar problems, the API returns a default service response with the appropriate status code and a descriptive status message.
• For most calls, if the error occurs because of a problem specific to the query, the API returns an Error. For example, if a create() request contains values to be updated for read-only fields.

Supported Entities

You can use ServiceAide Cloud Service Management (CSM) Web Service API's to access and change the following entity types:

• Attachment
• Change Request
• Configuration Item
• Communication
• Contact
• Defined Search
• Incident
• Knowledge Article
• Organization
• Problem
• Projects
• Service Request
• Support Group
• Task Ticket
• Ticket
• Value List
• Worklog

The list of supported entities can change in the future. Some entities may not be accessible to a particular user, depending on the permissions for the organization and user.

Supported Operations

API calls represent specific operations that your client applications can invoke at runtime to perform tasks. The CSM Web Services supports the following types of operations:

General Form of the CSM Web Service API

A request from a client initiates each API call and has a response from the server. API calls are never initiated from the server to the client. Each API call has a method name, which is one of the operations that are described in Supported Operations section.

The CSM Web Services API lets you encode calls using either SOAP (Simple Object Access Protocol) or XML-RPC, a simple RPC mechanism that is encoded in XML.

SOAP Implementation

The CSM Web Service API allows you to encode your calls using SOAP. SOAP (Simple Object Access Protocol) is an XML-based protocol for exchanging information. See http://www.w3.org/TR/SOAP/ for a detailed description of SOAP.

All the supported operations are available in the SOAP implementation. See Supported Operations section.

Each SOAP call must be made to a Service Desk application server hostname with a servlet name of webservices/xxxx. This section outlines the high-level SOAP specification for the Service Desk API.

See the Service Desk WSDL at http://www.w3.org/TR/SOAP/ for a more technical specification.

SOAP Namespaces

SOAP uses different namespaces for different elements and attributes. The namespace depends on the role that the data plays in the message formatting, handling, or encoding. The namespaces reflect how all data type definitions in SOAP are delegated to the XML schema.

The ServiceAide Cloud Service Management Web Service API uses the following namespaces.