Overview of the Management API guide

An overview of the Management API. The API provides management capabilities for Clouds and Integration Appliances.

The Management API is implemented as a web service. This web service provides a way to manage App Connect Appliances (Integration Appliances) and App Connect on Cloud (Cloud) projects through your applications or scripts.

The API provides Integration Appliance and Cloud management in the following areas:

Deployment: Provides operations to create, get, and delete configurations, rules, and projects. You can start, pause, stop, and cancel jobs. You can import or export repositories.

Security: Provides operations to create, get, list, and delete users, roles, and permissions. You can log in and log out by using the security WSDL.

Staging: Checks whether the staging database is started and starts or stops the staging database. (Applies to appliances only.)

System Administration: Sets or gets the appliance name or network configuration. You can also run system commands or get system information. (Applies to appliances only.)

Job Monitoring: Searches for job, gets job count, and gets job details. You can also set and get job monitoring properties.

Logs and Notifications: Saves, gets, and deletes notification policies. You can also get and set email and SNMP endpoints, set and get log levels, and get log count.

The Management API complies with the following web services standards:

Web Services Interoperability Organization (WS-I) Basic Profile 1.0
SOAP 1.1
Web Services Description Language (WSDL) 1.1
XML Schema 1.1

You can create client applications that call web services operations to manage and monitor Integration Appliances and Cloud projects. Communication between the client application and the Integration Appliance orCloud project is accomplished by using HTTP or HTTPS.

The Management API is defined in WSDL files. Client applications call web services operations by sending SOAP messages. SOAP messages are formatted in XML and so are programming language neutral.

Examples of SOAP messages

This section provides examples of logging in, getting a user and logging out using the Management API - Security WSDL.

The following code is an example of a SOAP request to log in.

Note: If you are using Management API for App Connect on Cloud, use the IBM ID credential for the username and password fields.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sec="http://www.approuter.com/schemas/2008/1/security">
 <soapenv:Header/>
 <soapenv:Body>
  <sec:login>
   <sec:username>webuser@mycompany.com</sec:username>
   <sec:password>D3nu9noB</sec:password>
  </sec:login>
 </soapenv:Body>
</soapenv:Envelope>

The following code is an example of a SOAP reply to the request to log in.

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
 <S:Body>
  <ns2:loginResponse xmlns:ns2="http://www.approuter.com/schemas/2008/1/
  security" xmlns:ns3="http://www.approuter.com/schema/router/1000/security/03">
   <ns2:sessionId>8F059BEEA3611033D277773A95404641</ns2:sessionId>
  </ns2:loginResponse>
 </S:Body>
</S:Envelope>

The sessionId is required to perform other SOAP operations after you log in to an Integration Appliance or the Cloud.

The following code is an example of a SOAP request to get a user.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sec="http://www.approuter.com/schemas/2008/1/security">
 <soapenv:Header>
  <sec:sessionId>8F059BEEA3611033D277773A95404641</sec:sessionId>
 </soapenv:Header>
 <soapenv:Body>
  <sec:getUser>
   <sec:username>webuser</sec:username>
  </sec:getUser>
 </soapenv:Body>
</soapenv:Envelope>

The following code is an example of a SOAP response to the request to get a user.

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
 <S:Body>
  <ns2:getUserResponse xmlns:ns2="http://www.approuter.com/schemas/2008/1/
  security" xmlns:ns3="http://www.approuter.com/schema/router/1000/security/03">
   <ns2:user>
    <ns3:id>8F059BEEA3611033D277773A95404641</ns3:id>
    <ns3:name>webuser</ns3:name>
    <ns3:encPasswd>{SHA}clO20r2ZJMJcDrNwXQzhWB8YcdI=</ns3:encPasswd>
    <ns3:displayName>WebServiceUser</ns3:displayName>
    <ns3:isActive>true</ns3:isActive>
    <ns3:isMutable>true</ns3:isMutable>
    <ns3:isVisible>true</ns3:isVisible>
    <ns3:email>webuser@mycompany.com</ns3:email>
    <ns3:createdTime>2010-03-02T22:11:32.935Z</ns3:createdTime>
    <ns3:failedLoginCount>0</ns3:failedLoginCount>
    <ns3:scopeId>B47EAECF6AD14AA028B4EA038CB742D0</ns3:scopeId>
    <ns3:scopeType>Tenant</ns3:scopeType>
   </ns2:user>
  </ns2:getUserResponse>
 </S:Body>
</S:Envelope>

The following code is an example of a SOAP request to logout.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sec="http://www.approuter.com/schemas/2008/1/security">
 <soapenv:Header>
  <sec:sessionId>8F059BEEA3611033D277773A95404641</sec:sessionId>
 </soapenv:Header>
 <soapenv:Body>
  <sec:logout/>
 </soapenv:Body>
</soapenv:Envelope>

Cloud examples

The following examples apply to the Cloud only.

The previous examples used SOAP operations that ran in a tenant in the Cloud or an Integration Appliance. To run operations in environments within a tenant in the Cloud, you use the setCurrentScope operation to set the scope to the environment where you want to run SOAP operations.

The following example sets the scope to the development environment and then starts a project located in the development environment.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sec="http://www.approuter.com/schemas/2008/1/security">
 <soapenv:Header>
  <sec:sessionId>63Y93HD6D856EB5812EB71216C3547W7</sec:sessionId>
 </soapenv:Header>
 <soapenv:Body>
  <sec:setCurrentScope>
   <sec:scopeName>Development</sec:scopeName>
  </sec:setCurrentScope>
 </soapenv:Body>
</soapenv:Envelope>

The following example is the SOAP response to the request.

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
 <S:Body>
  <ns2:setCurrentScopeResponse xmlns:ns2="http://www.approuter.com/
  schemas/2008/1/security" xmlns:ns3="http://www.approuter.com/schema/
  router/1000/security/03">
   <ns2:success>true</ns2:success>
  </ns2:setCurrentScopeResponse>
 </S:Body>
</S:Envelope>

The following example is a SOAP request to start a configuration in the development environment.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:dep="http://www.approuter.com/schemas/2008/1/deployment">
 <soapenv:Header>
  <dep:sessionId>63Y93HD6D856EB5812EB71216C3547W7</dep:sessionId>
 </soapenv:Header>
 <soapenv:Body>
  <dep:start>
   <dep:projectName>HTTP_363i</dep:projectName>
   <dep:version>1.0</dep:version>
   <dep:configName>HTTP_363j</dep:configName>
  </dep:start>
 </soapenv:Body>
</soapenv:Envelope>

The following example is the SOAP response to the request.

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
 <S:Body>
  <ns2:startResponse xmlns:ns2="http://www.approuter.com/schemas/2008/1/
  deployment" xmlns:ns3="http://www.approuter.com/schemas/2008/1/deployment/
  types" xmlns:ns4="http://www.approuter.com/schema/router/1000/security/03"
  xmlns:ns5="http://www.approuter.com/schemas/2008/1/util/types">
   <ns2:success>true</ns2:success>
  </ns2:startResponse>
 </S:Body>
</S:Envelope>