Overview

You can invoke actions by using the IBM Spectrum Protect Plus REST API. In IBM Spectrum Protect Plus, you use a session ID that is associated with a specific user account to send an HTTP request. After you request a session ID for a user account by providing the user name and password for the account, you must ensure that every HTTP request includes a valid session ID.

Before you begin

Ensure that you have the required permissions for any actions that you are planning. Permission settings for user accounts are managed by role-based access control. For more information, see the IBM Spectrum Protect Plus Installation and User’s Guide.

Methodology

Before you develop an application by using the IBM Spectrum Protect Plus REST API, consider using this methodology: 1. Run the procedure that you plan to develop by accessing IBM Spectrum Protect Plus through a web browser. Use several example instances and scenarios. 2. Generalize and design the procedure with the API.

To use the suggested methodology, complete the following steps:

  1. Open the IBM Spectrum Protect Plus. Open the login page and enter the username and the password of a specific user.

    If the credentails are valid, you access the Dashboard page as the user. In the back end, your browser receives 32 hexadecimals called session ID from IBM Spectrum Protect Plus and store the information temporarily. Every session ID is associated with that user. The session ID is valid for 45 minutes. If you navigate to another page in IBM Spectrum Protect Plus, you do not have to enter the username and the password because the session ID in your browser is used automatically. Keep the page open and do nothing for 45 minutes and you will log out of the session automatically.

  2. Access the IBM Spectrum Protect Plus REST API. If you have a valid session ID, use it; otherwise, request a new one by sending an HTTP request command with a username and a password, as described in Creating a session ID.

You wil receive an HTTP response that contains a session ID associated with that user. Use this session ID in your HTTP requests to invoke other actions such as running inventory jobs for hypervisors.

_images/overview_general_spp01.png

Figure 1 A flowchart of transactions between a client and the IBM Spectrum Protect Plus REST API

Response and request format: JSON

The IBM Spectrum Protect Plus REST API uses JavaScript Object Notation (JSON) for HTTP requests and responses.

Structure of an HTTP response message

The REST API follows a consistent structure for response messages. For example, you might send the following request to IBM Spectrum Protect Plus at the IP address of 10.0.0.100 to get site information.

GET     https://10.0.0.100/api/site

You receive the following response with the HTTP status code of 200 (OK).

{
    "links": {
        "self": {
            "rel": "self",
            "href": "https://10.0.0.100/api/site",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        },
        "create": {
            "rel": "create",
            "href": "https://10.0.0.100/api/site",
            "hreflang": null,
            "media": null,
            "title": null,
            "type": null,
            "deprecation": null
        }
    },
    "total": 3,
    "sites": [
        {
            "links": {
                "self": {
                    "rel": "self",
                    "href": "https://10.0.0.100/api/site/1000",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                "up": {
                    "rel": "up",
                    "href": "https://10.0.0.100/api/site",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                "edit": {
                    "rel": "update",
                    ...
                },
                "delete": {
                ...
                },
                "usedby": {
                    "rel": "related",
                    "href": "http://localhost:8082/api/endeavour/association/
↪resource/site/1000?action=listUsingResources",
                    ...
                },
                "resourceprovider": {
                    "rel": "related",
                    "href": "https://10.0.0.100/api/site/1000/resourceprovider",
                    ...
                }
            },
            "id": "1000",
            "name": "Primary",
            "description": "Primary Site",
            "defaultSite": false,
            "throttles": null,
            "demo": false,
            "rbacPath": "root:0/site:0/site:1000"
        },
        {...},
        {...}
    ]
}

The structure above can be generalized as below:

{
    "links":        <HATEOAS>,
    "total":        <objectCount>,
    "<objectType>": [
        {
            "links":          <HATEOAS>,
            "id":             <objectId>,
            "name":           <objectName>,
            "<requiredKey1>": <requiredValue1>,
            "<requiredKey2>": <requiredValue2>,
            ...,
            "<optionalKey1>": <optionalValue1>,
            "<optionalKey2>": <optionalValue2>,
            ...
        },
        {
            "links":          <HATEOAS>,
            "id":             <objectId>,
            "name":           <objectName>,
            "<requiredKey1>": <requiredValue1>,
            "<requiredKey2>": <requiredValue2>,
            ...,
            "<optionalKey1>": <optionalValue1>,
            "<optionalKey2>": <optionalValue2>,
            ...
        },
        <object3>,
        <object4>
        ...
    ]
}

HATEOAS and URI representation

Hypermedia as the Engine of Application State (HATEOAS) is a common methodology to provide users with interfaces of applications using REST architecture. Here is an example in IBM Spectrum Protect Plus. Recall the example response in the previous section and see what actions are represented as URIs based on HATEOAS.

IBM Spectrum Protect Plus REST API has operation parameters that can transform a JSON object in a response. For details, follow the instructions in Operation parameters for JSON object output.

Getting started

You can develop an application that interacts with IBM Spectrum Protect Plus via the REST API in various platforms, programming languages, scripting languages, and development tools, as describedin the following sections.