Working with REST

In this recipe, we will use the REST plugin. We will use it to connect to the Orchestrator Control Center REST API.

Getting ready

We need a REST-capable host you can contact. As every REST host handles things a little differently, we will use the REST interface Orchestrator and the Orchestrator Control Center, to showcase the functionality.

I have also collected some other Orchestrator-REST integration examples in the See also section of this recipe.

If you are new to REST, I would like to point you to the Accessing Orchestrator REST API recipe in Chapter 7, Interacting with Orchestrator.

How to do it...

This recipe is divided into connecting, gathering information, sending information, as well as creating workflows.

Connecting to a REST host

There are two methods (as of vRO7.1) to connect to a host. We will use the normal method here to connect to a REST host, as this showcases a lot of things you should know. The other one (using Swagger) is discussed in the There's more... section:

  1. Start the workflow by navigating to Library | HTTP-REST | Configuration | Add a REST host.
  2. Enter the name under which you want to save this connection.
  3. Enter URL to the REST API of the host.

    Orchestrator

    https://[Orchestrator]:8281/vco/

    Orchestrator Control Center

    https://[Orchestrator]:8283/vco-controlcenter/

  4. The default timeouts are OK. Make sure you accept the certificate; click on Next.
  5. Choose an authentication method (refer to the How it works... section) if you're unsure whether basic authentication will work with all clients; however, it isn't safe for production use.

    Orchestrator

    Orchestrator Control Center

    Authentication

    Basic

    Basic

    Session

    Shared or per user

    Shared (root)

  6. Choose whether you want to share the connection or use the current logged in Orchestrator user. Please remember that the Orchestrator Control Center has only the root user so you have to use shared for that.
  7. Choose whether you require a proxy to connect to the REST host. This means that Orchestrator will not connect to the REST host if the hostname you supplied isn't in the SSL certificate. For example, if you add the IP instead of the FQDN (and the IP isn't in the certificate as SAN) then Orchestrator will not connect to this host.
  8. The advanced setting can be left at the default for this example.

You have now added the REST host to Orchestrator. However, some REST interfaces (such as vCloud Director) require a certain path for login. To adjust to this behavior, you can have a look at the example workflow: Library | HTTP-REST Samples | Set vCloud Director Authentication to a REST host.

Using GET

We will now demonstrate a GET request to a REST host. GET gets information from a REST host:

  1. Start the workflow by navigating to Library | HTTP-REST | Configuration | Add a REST operation.
  2. Select the REST host to which you want to add the operation.
  3. Give the operation a name for the inventory, such as About or Status.
  4. Add the template URL. The template URL is the URL that you will use the method on (in our example here, GET). Use the following examples:

    Orchestrator

    /api/about/

    Displays version information of Orchestrator.

    Control Center

    /api/server/status

    Displays the status of the Orchestrator service.

  5. Submit the workflow and wait until it has finished.
  6. Start the workflow Library | HTTP-REST | Invoke a REST operation.
  7. Select the REST operation you created above from the inventory and submit it.

You will see that the GET on Orchestrator will result in a string that contains a JSON object. Have a look at the logs. The Orchestrator will show:

Content as string: {"version":"7.0.1.3533702","build-number":"3533702","build-date":"2016-02-09T12:19:45Z","api-version":"5.5.2"}

Whereas the Control Center shows an error (all in red), which shows:

Error in (Workflow:Invoke a REST operation / Check status code (item3)#1) HTTPError: status code: 415

This is due to the way the default content type is used in the request. Check the How it works... section of this recipe.

Using POST

While GET gets information, POST will alter, create, or transfer information on the REST host:

  1. Start the workflow by navigating to Library | HTTP-REST | Configuration | Add a REST operation.
  2. Select the REST host to which you want to add the operation.
  3. Give the operation a name for the inventory, such as Info or Start.
  4. Add the Template URL and Content type with the following content:

    Host

    Template URL

    Content type

    Orchestrator

    /api/workflows/{id}/executions

    application/xml

    Orchestrator Control Center

    /api/server/status/start

    application/json

The {id} part will be replaced later at execution.

  1. Select POST and Submit the workflow.

    Before we can execute the workflow, we need to get the ID of the workflow. In this example, we will use the example workflow 00.00 BasicsWorkflow. Using the Orchestrator Client, browse the workflow and copy its ID from the General tab (for example, 312b7be1-abd2-47b6-9bc9-9e44c80ad168):

  2. Start the workflow by navigating to Library | HTTP-REST | Invoke a REST operation.
  3. Select the REST operation from the inventory.
  4. For the Orchestrator POST enter the ID of the workflow under Parameter 1.
  5. For the Orchestrator POST enter the following under Content:
          <execution-context xmlns="http://www.vmware.com/vco"> 
          <parameters> 
              <parameter type="string" name="input" scope="local"> 
                  <string>Entry String</string> 
              </parameter> 
          </parameters> 
      </execution-context>
  6. For the Control Center just leave everything at the defaults.
  7. Submit the workflow and use the Orchestrator Client to see the result.

The POST request requires you to enter additional information. The content is in the string form; however, it contains XML. The return code should be a 202 status code, which means that the request was accepted.

The Control Center doesn't need extra information but executes a command that starts the Orchestrator service on the selected host.

Creating a workflow from a REST operation

To create a workflow out of a REST operation, follow these steps:

  1. Start the workflow by navigating to Library | HTTP-REST | Generate a new workflow from a REST operation.
  2. Select the REST operation; if you are using a POST, you will also see the content type you entered.
  3. Give the new workflow a name and select a folder for it.

When running the workflow, you will be required to enter the same variables that you entered when using the Invoke a REST operation workflow.

Phrasing the return value

For the examples we are looking at, there are only two return types; XML and JSON.

XML parsing is discussed in the Working with XML recipe in Chapter 10, Built-in Plugins.

JSON parsing is shown in the Introduction to Chapter 7, Interacting with Orchestrator.

Using the Swagger spec URL

The other method to connect a host, and probably the best one for Control Center, uses the workflow Add a REST host by Swagger spec from a URL.

Swagger is a method describing the operations of a REST host. The interface is pretty common nowadays but not every REST host uses it yet.

To try it out, we will add the Orchestrator Control Center using the following method:

  1. Start the workflow by navigating to Library | HTTP-REST | Configuration | Add a REST host by Swagger spec from a URL.
  2. Enter a name for the connection.
  3. As the Swagger spec URL, enter: https://[FQDN Orchestrator control Center]:8283/vco-controlcenter/api/api-docs.
  4. Choose HTTPS and enter application/json as the default content type.
  5. Accept the certificate silently and click Next.
  6. Enter the authentication to the Swagger, which can be different to the products authentication. In the case of the Control Center you are connecting with root. Click Next.
  7. Choose Basic Authentication and use the credentials that will execute the REST operation. In the case of the Control Center you are connecting with root. Click Next.
  8. Choose weather you want to check the hostname. Just select No and Submit the workflow.
  9. Check your Orchestrator inventory. You should now have all the GETs, PUTs, and so on that are associated with your REST service.

How it works...

REST stands for Representational State Transfer and is the way that most applications nowadays use an interface. Even Orchestrator itself switched from a SOAP interface to a REST interface.

Authentications

Orchestrator can use the following authentication methods out-of-the-box:

Method

Description

None

Doesn't use any authentication at all.

OAuth

A token-based authentication. For the difference between v1 and v2, see  https://blog.apigee.com/detail/oauth_differences .

Basic

Basic authentication, no encryption, and clear text passwords.

Digest

Provides a basic encrypted authentication.

NTLM

NTLM (NT LAN Manager) provides encryption using the Window Security Support Provider (SSPI) framework.

Kerberos

Encrypted authentication using tickets. Also see the Configuring the Kerberos authentication recipe in Chapter 2, Optimizing Orchestrator Configuration.

Taking a look at the code behind the workflows, we find that authentications are created by the RESTAuthenticationManager object using the createAuthentication()method. This method requires the authentication type (Basic, OAuth 1.0, and so on) as well as the authentication parameters (authParams). The authParams variable can have different content depending on the REST host and login method used. Take a look at this example:

Method

Usage

OAuth 1.0

var authParams = [consumerKey, consumerSecret, accessToken, accessTokenSecret];

OAuth 2.0

var authParams = [oauth2Token];

Basic

var authParams = [sessionMode, authUserName, authPassword];

vCD

var authParams = [sessionMode, username, password, organization, loginUrl];

So, if you have trouble connecting to your REST host, you can simply alter authParams to the specifications of your REST host.

Working with the results of a REST request

Let's take a look at the results of a request. The results are part of the RESTResponse object. The two important attributes of this object for most users are contentAsString and statusCode. The statusCode attribute contains the status code of the request. You can view the basic response codes at https://[IP or FQDN Orchestrator]:8281/vco/api/docs/rest.html.

The contentAsString attribute returns a string that represents which is returned, which is XML in case of the Orchestrator and JSON in case of the Control Center. You can use the information in the Working with XML recipe in Chapter 10, Built-in Plugins or the JavaScript complex variables recipe in Chapter 6, Advanced Programming to phrase the return code.

Default content type

The error we get in the GET of the Control Center is related to the fact that we didn't (or better, couldn't) define a default content type (Header). Other REST servers, such as vCloud Director, might also need some more headers. To fix this you can do the following:

Method A:

  1. Generate a new workflow from a (non-working) REST operation and edit it.
  2. Edit the scriptable task and find the following section:
          //Customize the request here 
      //request.setHeader("headerName", "headerValue");
  3. Uncomment request.setHeader and replace the header content:
          request.setHeader("content-type", "application/jso");
  4. Save and run the workflow.

Method B:

  1. Duplicate the workflow Library | HTTP-REST | Configuration | Add a REST operation.
  2. Edit the workflow and remove the Show parameter input from the workflow presentation of the defaultContentType variable.
  3. Now add the workflow and set the default content type to application/json.

See also

The example workflows are as follows:

  • 09.04.1 Copy of Add a REST operation
  • 09.04.2 Invoke 'status: GET /server/status'
  • 09.04.3 Invoke 'start Orchestrator Service: POST server/status/...'
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset