RESTful APIs

IBM® Spectrum Conductor can be configured and managed through RESTful APIs.

About this task

The RESTful APIs are hosted on:

The REST web server, which hosts the RESTful APIs for resource management and package deployment.
The ascd web server, which hosts the RESTful APIs for instance group and application instance management.

When you are using the RESTful APIs and API reference documentation, take note of the following information:

When you open the RESTful APIs reference documents in the same browser as the cluster management console, clear your browser cache to avoid potential caching issues between the API reference cookies and the cluster management console cookies.
When you authenticate credentials to run the post/put/delete Try it out commands in the cluster management console for the new RESTful APIs, any previously authenticated tokens that you have in the cluster management console are overwritten. If you had the cluster management console open in another tab, it is no longer authenticated.
When you use the Try it out action within a PUT request, the PUT request might be denied by the security guard due to missing or invalid tokens. This happens when your current session is already logged into the cluster management console. Clear your cache and try again.

To view the offline RESTful API documentation, see RESTful API references.

Procedure

Follow these steps to locate and access the RESTful APIs:

Run the command for the APIs you want to access.
- For the location of the resource management and package deployment APIs, hosted on the REST web server, run:
```
egosh client view REST_BASE_URL_1
```
- For the location of the instance group and application instance management APIs, hosted on the ascd web server, run:
```
egosh client view ASCD_REST_BASE_URL_1
```
The description in the results shows the base URL in the format https://HOSTNAME:PORT/platform/rest/.
Append the appropriate keywords to access the APIs. The /v1 suffix in the path corresponds to the current API version.
- For the resource management APIs, append ego or ego/v1 to the end of the base URL. For example:
```
https://myresthost.example.com:8543/platform/rest/ego/v1
```
- For the deployment APIs, append deployment/v1 to the end of the base URL. For example:
```
https://myresthost.example.com:8543/platform/rest/deployment/v1
```
- For the instance group APIs, append conductor/v1 to the end of the base URL. For example:
```
https://myascdhost.example.com:8643/platform/rest/conductor/v1
```
- For the application instance APIs, append asc/v1 to the end of the base URL. For example:
```
https://myascdhost.example.com:8643/platform/rest/asc/v1
```
Append cloud/apis/explorer to the host URL after the port number to access the RESTful API reference documentation.
- If the resource management and deployment APIs are located on port 8543, append the following URL to access each of the RESTful API reference documents:
```
https://myresthost.example.com:8543/cloud/apis/explorer
```
- If the instance group and application instance APIs are located on port 8643, append the following URL to access each of the RESTful API reference documents:
```
https://myascdhost.example.com:8643/cloud/apis/explorer
```
Web server communication is by default secured over SSL. If you disabled SSL during installation (by setting the DISABLESSL=Y environment variable), skip this step. Otherwise, when the browser prompts you about an untrusted connection, import the web server certificate:

These steps apply only if you are using the default self-signed certificate. If you are using a properly chained certificate that is issued or signed by a trusted certificate authority in a production environment, follow the instructions provided by your certificate authority.
- If you are using Chrome on Windows, complete the following steps:
  1. Click Settings > Advanced > Privacy and Security > Manage Certificates > Import.
  2. Follow the Certificate Import Wizard, import the downloaded cacert.pem, click Place all certificates in the following store, click Browse, select Trusted Root Certification Authorities, and click OK.
  3. Complete the wizard and accept any additional prompts.
  4. Restart the browser, if required.
- If you are using Chrome on Mac OS, complete the following steps. You are required to enter your Keychain password for some of these steps:
  1. Double-click the cacert.pem file in the Finder.
  2. In the Add Certificates window, select System from the Keychain drop-down menu.
  3. Click Add.
  4. In the Keychain Access window, select the System tab and double-click the imported certificate.
  5. Under Trust, select Always Trust for all of the drop-down options.
  6. Exit the Keychain and restart the browser.
- If you are using Firefox on Windows or Linux®, complete the following steps:
  1. Click Add Exception.
  2. In the Add Security Exception dialog, click View.
  3. In the Certificate Viewer dialog, click the Details tab.
  4. Select Platform Root CA (SHA256) and click Export.
  5. Save the certificate (PlatformRootCA(SHA256).crt) to a local directory.
  6. Click Tools > Options > Advanced > View Certificates.
  7. Click the Authorities tab and click Import.
  8. Browse to the location where you saved the certificate and select it.
  9. When prompted to trust a new CA, ensure that you select Trust this CA to identify websites and click OK.
  10. Restart the browser, if required.
- If you are using Firefox on Mac OS, complete the following steps:
  1. Click Add Exception....
  2. In the Add Security Exception dialog, click View.
  3. In the Certificate Viewer dialog, click the Details tab.
  4. Select Platform Root CA (SHA256) and click Export.
  5. Save the certificate (PlatformRootCA(SHA256).crt) to a local directory.
  6. Click Firefox > Preferences > Advanced > View Certificates.
  7. Click the Authorities tab and click Import.
  8. Select the certificate from the location where it is saved on your system.
  9. When prompted to trust a new CA, ensure that you select Trust this CA to identify websites and click OK.
  10. Restart the browser, if required.
Log in using the same login credentials as you use to access the cluster management console.