A URI represents a CA Automation Point resource upon which operations are performed. The meaning of an HTTP method is determined by the specified URI. The API documentation is organized alphabetically by each resource URI and HTTP method. These methods accomplish each CA Automation Point operation, and identify the XML documents that are required or delivered by that operation.
These methods are documented in:
The base name of a URI targeted to a CA Automation Point web service running under Tomcat on the local machine using TLS would be:
https://localhost:8443/apwebsvc
This example base name is used for all URIs listed in the upcoming sections. In practice, a specific host name is used by a client application running on another computer. Further, a site can choose to configure Tomcat to use a non-default port number. Finally, during initial testing, a site may choose to avoid TLS for simplicity. That site would then use the http scheme and the non-TLS default Tomcat port of 8080. Utilize your site-specific values for any URI in upcoming examples. The remainder of the URI reflects the CA Automation Point resource of interest.
URIs can contain characters that are not normally allowed in a URI. Such special characters must be percent-encoded as per the Internet Engineering Task Force RFC 3986. Some CA Automation Point XML reply documents contain URIs. These URIs are not percent-encoded. If such a URI is used as the target URI for another web service request, it must be percent-encoded before making that second request. Direct programmed calls to the web service API, must be percent-encode such that a URI before using it as the target URI of another request. The UTF-8 character set must be used to percent-encode the URIs sent to CA Automation Point web services.
The CA RequestService client-side API and command-line program automatically percent-encode any supplied URI. Thus, when using those CA client components, customer programs must not percent-encode the URIs supplied to those CA client components.
When issuing a web service request from the command line using the CA RequestService client application, be aware of special characters that your operating system recognizes. These special characters are likely introduced when specifying a query, which is expressed as part of the URI. When the URI contains such special characters, enclose this URI in double quotes. The command interpreter for your operating system does not interpret special characters when enclosed in double quotes. For example, when requesting a list of all sessions that are automated, you issue a GET request with a query:
https://localhost:8443/apwebsvc/sessions?Automated=yes
On a Windows operating system, the equals sign is interpreted by the Windows Command Interpreter. The syntax is not interpreted as a single URI parameter, and the command fails. To prevent Windows from misinterpreting this parameter, enclose the parameter in double quotes:
“https://localhost:8443/apwebsvc/sessions?Automated=yes”
As each XML document is identified in one of the described methods, the XML schema that defines that document is specified. The XML schemas for all CA Automation Point web service XML documents are contained in:
%ap_home%\distrib\websvc\*.xsd
Documentation for all AP web service XML schemas is contained in:
%ap_home%\Doc\help\websvc\xmlSchemas\*.html
These XML documents explicitly identify the character set used to encode international characters within the XML document. The ‘encoding’ attribute of the XML ‘document type declaration’ is used to specify the desired character set. Data within the XML document must be binary-encoded in the character set specified by the encoding attribute, or incorrect data is transmitted to the CA Automation Point server.
All CA Automation Point sample XML documents for Windows and Linux specify an encoding value of UTF-8. The samples for z/OS specify an encoding value of IBM1047. When CA Automation Point web service components move an XML document into a Java String or transmit the document over a TCP/IP connection, they re-encode the data for the appropriate character set. When these components re-encode the XML data, they also alter the XML encoding attribute of the document to reflect the character set being used.
For example, when the RequestService command-line client outputs an XML reply document to standard output, it uses the default character set for the operating system. On the Windows operating system, the default character set is code page 1252. Thus, when RequestService displays an XML document on standard output on a Windows computer, the data is encoded with code page 1252 and the XML encoding attribute contains the value ‘encoding=windows-1252’.
One final consideration is that the CA Automation Point Desktop server application processes its data in the Windows OEM code page. XML input documents can be encoded with UTF-8 or any other character set supported by the Java virtual machine. The actual character must exist in the OEM code page of the Windows server computer that is running CA Automation Point. For example, not all characters in the UTF-8 character set can be mapped to an identical representation in the commonly used OEM code page 850. When such a character cannot be represented in the OEM code page, the character is typically displayed as an unexpected graphic character.
In XML documents, CA Automation Point web services utilize namespaces to avoid naming conflicts. Set the CA Automation Point web service namespace as the default namespace in an attribute of the root element. Setting this attribute allows all CA Automation Point elements to not require qualifiers in this document. Each CA Automation Point XML document is validated against the XML schema, which defines that document. Specify the name of the schema as an attribute in the root element.
Example General Format:
<?xml version="1.0" encoding="utf-8"?> <YourXMLDocumentRootElement
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ca.com/distauto/ap/websvc/msgData XmlSchemaName.xsd" xmlns="http://www.ca.com/distauto/ap/websvc/msgData">
<ContentOfYourXMLDocument> </YourXMLDocumentRootElement>
Note: Only the XML schema name (bolded) changes from one document to another.
Example Specific Case:
This example sends a simple notification.
<?xml version="1.0" encoding="utf-8"?> <NotificationRequest
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ca.com/distauto/ap/websvc/msgData NotificationRequest.xsd" xmlns="http://www.ca.com/distauto/ap/websvc/msgData">
<Name>PersonThatYouWantToNotifiy</Name> <Tell>Hi. This is a notification test.</Tell> </NotificationRequest>
|
Copyright © 2014 CA Technologies.
All rights reserved.
|
|