Previous topic

Using Platform Services

Next topic

Scenarios

Odin Automation SDK
Last updated 20-Jun-2017

Using APS REST API

REST Client

To get access to the APS bus, you should use a REST client, for example:

  • cURL - universal library and utility for transferring data and sending messages, typically used in various scripts as demonstrated later in this document. In modern operating systems, it is available by default. Besides, many programming packages, for example PHP, contain cURL components in their libraries.
  • Advanced REST Client - a web developer helper UI tool to create and test HTTP requests.
  • RESTClient APS - APS specific REST client installed as a Firefox extension.

Once you have a REST client, ensure that you have a method to generate a token you are going to use in your requests on the APS bus.

Security Token

To generate a user token on your test platform, use the following steps:

  1. Log in to the provider control panel (PCP).
  2. Ensure the platform is in the Development mode. To check this:
    • Navigate to System > Settings and click System Properties.
    • Verify if the APS development mode is Enabled. Otherwise, click the Edit button on the bottom of the screen and switch the system to this mode.
  3. Navigate to System > Settings and in the Integration section click User APS tokens. You will see a list of users. The highest permissions are assigned to admin. Use the admin’s token if your solution requires the highest permissions.
  4. Click on the selected user and save the current token displayed on the screen.

Note

A user token is valid only for a short period of time, depending on the platform version - from 5 to 30 minutes. On its expiration, you have to update the token.

REST Requests

Keep nearby the list of APS controller operation collections and the list of APS controller all operations.

The following examples illustrate how to use REST clients to call operations at the APS controller. We assume that the operations are performed on a sandbox installed on the a.isv1.apsdemo.org domain.

Using REST Client UI

The following examples show how to operate APS resources available for a customer using the Advanced REST Client. Let us suppose, the customer administrator is John Smith.

List All Resources

Let us get a list of resources available for the customer.

  1. Get the user token for John Smith as explained in the Security Token section.

  2. Open the Advanced REST Client.

  3. Ensure, the APS-Token header is available there. If you open the REST client for the first time, add the APS-Token header. For example, on the Raw headers tab, enter “APS-Token:” in the new empty line.

  4. Paste the user token to the value field of the APS-Token header.

  5. On the Request tab, in its URI field, enter the proper URL, for example, http://a.isv1.apsdemo.org:8080/aps/2/resources.

  6. In the list of methods, select GET.

  7. Click SEND.

    ../../_images/Advanced_REST_client_get_resources.png
  8. If the response status is 200: OK, analyze the returned data. The following response contains a list of 30 resources. One of them is opened to look for its details.

    ../../_images/Advanced_REST_client_response.png

Every resource representation contains the aps section containing general properties of the APS resource. Pay attention to the following key properties that you will need when managing the resources:

  • aps.id - is a unique resource APS ID assigned by the APS controller. When updating a resource, a REST request must specify the resources APS ID in the request URI.
  • aps.subscription - is the APS ID of the customer subscription used to provision (create) the resource. When provisioning a new resource, a REST request must also specify the subscription APS ID. The platform must verify if the specified subscription allows creating one more resource.
  • aps.type - is the ID of the APS type that specifies a JSON schema used to create the resource. Every REST request for creating or updating a resource must specify an APS type.

Update a Resource

Let us change the state of the VPS presented in the list of resources from Stopped to Running. This goal requires you to specify the following in a REST request:

  • APS ID of the resource - the APS controller needs to know which APS resource you are going to change.
  • APS type of the resource - the APS controller needs to know which schema to use when changing resource properties (yes, it is possible to specify several properties to change).
  • At last, the property with its new value.

Compared with the previous example, change the following in the REST request:

  1. Copy the APS ID of the resource from the previous response to use it in the new request.

  2. Add the APS ID to the request URI as follows:

    http://a.isv1.apsdemo.org:8080/aps/2/resources/854601d9-550a-496e-8e07-3c7e62b2612d
    
  3. In the list of methods, select PUT.

  4. In the Raw payload field, enter the resource APS ID and APS type in the aps section and the updated property as in this example:

    {
       "aps": {
          "id": "854601d9-550a-496e-8e07-3c7e62b2612d",
          "type": "http://aps-standard.org/samples/async1pn/vps/1.0"
       },
       "state": "Running"
    }
    
  5. Click SEND.

    ../../_images/Advanced_REST_client_put_request.png
  6. If the response status is 200: OK, analyze the returned data

    ../../_images/Advanced_REST_client_put_response.png

    Pay attention to the changed state property in the response from the APS controller.

Using cURL

When sending a REST request through cURL, use the following sample formats:

  • GET request:

    # curl -k -X GET -H 'APS-Token:<value>` \
      https://<management-node>:6308/aps/2/resources/
    

    When getting collections other than resources, use the respective URI suffix instead of /aps/2/resources/. For example, to get a list of all APS types, use /aps/2/types/.

  • POST request:

    # curl -k -X POST -d @<file-name> -H 'APS-Token:<value>` \
      -H 'APS-Subscription-ID:<value>' \
      https://<management-node>:6308/aps/2/resources/
    

    <file-name> is the name of the file containing the JSON representation of the new resource to be created.

  • PUT request:

    # curl -k -X PUT -d @<file-name> -H 'APS-Token:<value>` \
      https://<management-node>:6308/aps/2/resources/<value>
    
  • DELETE request:

    # curl -k -X DELETE -H 'APS-Token:<value>` \
      https://<management-node>:6308/aps/2/resources/<value>
    

Note

If, like in the previous examples, you are using a sandbox ordered at the APS developer portal and your company name is “isv1”, the <management-node> will probably be a.isv1.apsdemo.org.