NetBackup^™ 8.2 API - Getting Started

Introduction

The NetBackup API provides a web-service based interface to configure and administer NetBackup, the industry leader in
data protection for enterprise environments.

NetBackup API is RESTful

The NetBackup API is built on the Representational State Transfer (REST) architecture, which is the most widely used
style for building APIs. The NetBackup API uses the HTTP protocol to communicate with NetBackup. The NetBackup API is
therefore easy to use in cloud-based applications, as well as across multiple platforms and programming languages.

JSON message format

The NetBackup API uses JavaScript Object Notation (JSON) as the message format for request and response messages.

The client-server relationship

The NetBackup API employs client-server communication in the form of HTTP requests and responses.

The API client (your program) uses the HTTP protocol to make an API request to the NetBackup server.
The NetBackup server processes the request. The server responds to the client with an appropriate HTTP status code
indicating either success or failure. The client then extracts the required information from the server's response.

Overview

Authentication

NetBackup authenticates the incoming API requests based on a JSON Web Token (JWT) or an API key that needs to be
provided in the Authorization HTTP header when making the API requests.

A JSON Web Token (JWT) is acquired by executing a login API request.
An API key is acquired by executing a api-keys API request.
A NetBackup API key is a pre-authenticated token that lets a NetBackup user run NetBackup commands
(such as nbcertcmd -createToken or nbcertcmd -revokeCertificate) or access NetBackup RESTful APIs.
Unlike a password, an API key can exist for a long time and you can configure its expiration.
Therefore, once an API key is configured, operations like automation can run for a long time using the API key.
More details around API keys can be found in NetBackup Security and Encryption Guide: http://www.veritas.com/docs/DOC5332.

TIP:
The port that is used to access the NetBackup API is the standard NetBackup PBX port, 1556.

Example of generating and using JWT for authentication

The following procedure provides a sample workflow to retrieve job information from NetBackup. This procedure involves
logging in to NetBackup to receive a JWT and then requesting job information for a specific job (job ID 5 in this
scenario).

Step 1
Use the NetBackup API endpoint POST /login to create a login request:

curl -X POST https://masterservername:1556/netbackup/login         \
     -H 'content-type: application/vnd.netbackup+json;version=1.0' \
     -d '{                                                         \
            "domainType":"vx",                                     \
            "domainName":"mydomain",                               \
            "userName":"myusername",                               \
            "password":"mypassword"                                \
        }'

The following response to the login request contains the JSON Web Token (JWT):

NOTE:
This response contains three attributes: token, tokenType and validity. The token attribute provides the JWT.
The validity attribute indicates that the token returned is valid for 86400 seconds, or 24 hours.

  {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsInppcCI6IkRFRiJ9.eNp0VF1v2jAU_S9-nHiArXQrb15yaT2cOLIdEJ2mKGWZmnXARMKEVvW_13EciO3weu65H-d-vaIyr9FsMp18Gt_dTsefb6bjESqrCs3Q7umYbfOqLg5ohH7XpYIWqwVfzNM1k6tHvCKJMhSnv63_5MvHO-V_cztC1fFJkQ_b3bGaHar6UGxeitm_k2Lnx_o5q_cvxW44Wlll-c9t2Vjrw7FokW2-eS53hcJ-5X-qwoT5n232u7o4qfJfEQchMZfZN_YVzb6jD-jHSGOMQ0YifA9ndElg5dJAZg9MyDMUcMASsmUkgC-B96jGYrFDoKCwgFEKgSQsPlsoETILgEsyJ4HyE2dLxEIyX9txDJYwSoK1Xa_F01EFZcLnZJgS3MOBNxEhDhNGYi9Tr7KLdJZ4JXBYsgUM0nUtnFFfmirQ7ZBUUZzm6EwEHClDmbTBKczEtacZK55kkXJuwrjcflm6gq45Tgne7I1_o9XF8CNPqdMTnIZEUnYvXLIjQZPnEIoQS2yjAwPVuJLrIFioFfYy4VQ-6JY70hLgERGiv6gad2SYVR9Ya822h6mOKI3sSXRnwSGEWBJMnTLsszTZhpbfarnh9cfI9_saN08DbzZF87m6RcSxyqAKoK63o9RsrJWnPd2zdq-5A8MRqUjUNllN6I4BgpQTuU44S7zzHOqQyeJdboDjAKiVor2YK8_nMutL7DQJux-m_KIIYukvnrthumPCbaS9BCbwkB5j8vW0cYZGfPVrXZHqrHrvU7tfsWmY9wf0Onakt7d3AAAA__8.VVE25rQqbrC-isGOqbRTqMPoK4ts5-9_6zSgz0fUg11m9GCClq10PS9u1DlaXye-S2MYYyHVEHSVs6uKcPVvN2WGBHkv7t-c4Hixc9O8zrJYhJaP979wF_gn08YnRlX7_o4Qj6muc1IWHjK0hPMIgq0X-sBU2Git9uppVW1jbLA",
      "tokenType": "BEARER",
      "validity": 86400
  }

Step 2
Get the job information using the NetBackup API endpoint GET /admin/jobs/{jobId}. In this example, the information for
the job ID 5 is requested.

NOTE:
The Authorization header uses the value of the token attribute from the response to the login
request made in the previous step.

curl -X GET https://masterservername:1556/netbackup/admin/jobs/5 \
     -H 'Accept: application/vnd.netbackup+json;version=2.0'     \
     -H 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsInppcCI6IkRFRiJ9.eNp0VF1v2jAU_S9-nHiArXQrb15yaT2cOLIdEJ2mKGWZmnXARMKEVvW_13EciO3weu65H-d-vaIyr9FsMp18Gt_dTsefb6bjESqrCs3Q7umYbfOqLg5ohH7XpYIWqwVfzNM1k6tHvCKJMhSnv63_5MvHO-V_cztC1fFJkQ_b3bGaHar6UGxeitm_k2Lnx_o5q_cvxW44Wlll-c9t2Vjrw7FokW2-eS53hcJ-5X-qwoT5n232u7o4qfJfEQchMZfZN_YVzb6jD-jHSGOMQ0YifA9ndElg5dJAZg9MyDMUcMASsmUkgC-B96jGYrFDoKCwgFEKgSQsPlsoETILgEsyJ4HyE2dLxEIyX9txDJYwSoK1Xa_F01EFZcLnZJgS3MOBNxEhDhNGYi9Tr7KLdJZ4JXBYsgUM0nUtnFFfmirQ7ZBUUZzm6EwEHClDmbTBKczEtacZK55kkXJuwrjcflm6gq45Tgne7I1_o9XF8CNPqdMTnIZEUnYvXLIjQZPnEIoQS2yjAwPVuJLrIFioFfYy4VQ-6JY70hLgERGiv6gad2SYVR9Ya822h6mOKI3sSXRnwSGEWBJMnTLsszTZhpbfarnh9cfI9_saN08DbzZF87m6RcSxyqAKoK63o9RsrJWnPd2zdq-5A8MRqUjUNllN6I4BgpQTuU44S7zzHOqQyeJdboDjAKiVor2YK8_nMutL7DQJux-m_KIIYukvnrthumPCbaS9BCbwkB5j8vW0cYZGfPVrXZHqrHrvU7tfsWmY9wf0Onakt7d3AAAA__8.VVE25rQqbrC-isGOqbRTqMPoK4ts5-9_6zSgz0fUg11m9GCClq10PS9u1DlaXye-S2MYYyHVEHSVs6uKcPVvN2WGBHkv7t-c4Hixc9O8zrJYhJaP979wF_gn08YnRlX7_o4Qj6muc1IWHjK0hPMIgq0X-sBU2Git9uppVW1jbLA'

The response to the GET request contains the job information for job ID 5:

{
    "data": {
        "links": {
            "self": {
                "href": "/admin/jobs/5"
            },
            "file-lists": {
                "href": "https://masterservername:1556/netbackup/admin/jobs/5/file-lists"
            },
            "try-logs": {
                "href": "https://masterservername:1556/netbackup/admin/jobs/5/try-logs"
            }
        },
        "type": "job",
        "id": "5",
        "attributes": {
            "jobId": 5,
            "parentJobId": 0,
            "activeProcessId": 27116,
            "mainProcessId": 0,
            "jobType": "IMAGEDELETE",
            "jobSubType": "IMMEDIATE",
            "policyType": "STANDARD",
            "policyName": "",
            "scheduleType": "FULL",
            "scheduleName": "",
            "clientName": "",
            "controlHost": "",
            "jobOwner": "root",
            "jobGroup": "",
            "backupId": "",
            "sourceMediaId": "",
            "sourceStorageUnitName": "",
            "sourceMediaServerName": "",
            "destinationMediaId": "",
            "destinationStorageUnitName": "",
            "destinationMediaServerName": "",
            "dataMovement": "STANDARD",
            "streamNumber": 0,
            "copyNumber": 0,
            "priority": 0,
            "retentionLevel": 0,
            "compression": 0,
            "status": 1,
            "state": "DONE",
            "done": 1,
            "numberOfFiles": 0,
            "estimatedFiles": 0,
            "kilobytesTransferred": 0,
            "kilobytesToTransfer": 0,
            "transferRate": 0,
            "percentComplete": 0,
            "currentFile": "",
            "restartable": 0,
            "suspendable": 0,
            "resumable": 0,
            "killable": 1,
            "frozenImage": 0,
            "transportType": "LAN",
            "dedupRatio": 0,
            "currentOperation": 0,
            "jobQueueReason": 0,
            "jobQueueResource": "",
            "robotName": "",
            "vaultName": "",
            "profileName": "",
            "sessionId": 0,
            "numberOfTapeToEject": 0,
            "submissionType": 0,
            "acceleratorOptimization": 0,
            "dumpHost": "",
            "instanceDatabaseName": "",
            "auditUserName": "",
            "auditDomainName": "",
            "auditDomainType": 0,
            "restoreBackupIDs": "",
            "startTime": "2018-01-09T10:03:22.000Z",
            "endTime": "2018-01-09T10:03:23.000Z",
            "activeTryStartTime": "2018-01-09T10:03:22.000Z",
            "lastUpdateTime": "2018-01-09T10:03:23.256Z",
            "kilobytesDataTransferred": 0,
            "try": 1
        }
    }
}

Example of generating and using an API key for authentication

The following procedure provides a sample workflow to retrieve job information from NetBackup.
This procedure involves logging onto NetBackup to receive a JWT and then creating an API key
that uses the JWT. Then use this API key for fetching information of a specific job
(job ID 5 in this scenario).

Step 1
Use the NetBackup API endpoint POST /login to create a login request:

curl -X POST https://masterservername:1556/netbackup/login         \
     -H 'content-type: application/vnd.netbackup+json;version=1.0' \
     -d '{                                                         \
            "domainType":"vx",                                     \
            "domainName":"mydomain",                               \
            "userName":"myusername",                               \
            "password":"mypassword"                                \
        }'

The following response to the login request contains the JSON Web Token (JWT):

NOTE:
This response contains three attributes: token, tokenType and validity. The token attribute provides the JWT.
The validity attribute indicates that the token returned is valid for 86400 seconds, or 24 hours.

  {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsInppcCI6IkRFRiJ9.eNp0VF1v2jAU_S9-nHiArXQrb15yaT2cOLIdEJ2mKGWZmnXARMKEVvW_13EciO3weu65H-d-vaIyr9FsMp18Gt_dTsefb6bjESqrCs3Q7umYbfOqLg5ohH7XpYIWqwVfzNM1k6tHvCKJMhSnv63_5MvHO-V_cztC1fFJkQ_b3bGaHar6UGxeitm_k2Lnx_o5q_cvxW44Wlll-c9t2Vjrw7FokW2-eS53hcJ-5X-qwoT5n232u7o4qfJfEQchMZfZN_YVzb6jD-jHSGOMQ0YifA9ndElg5dJAZg9MyDMUcMASsmUkgC-B96jGYrFDoKCwgFEKgSQsPlsoETILgEsyJ4HyE2dLxEIyX9txDJYwSoK1Xa_F01EFZcLnZJgS3MOBNxEhDhNGYi9Tr7KLdJZ4JXBYsgUM0nUtnFFfmirQ7ZBUUZzm6EwEHClDmbTBKczEtacZK55kkXJuwrjcflm6gq45Tgne7I1_o9XF8CNPqdMTnIZEUnYvXLIjQZPnEIoQS2yjAwPVuJLrIFioFfYy4VQ-6JY70hLgERGiv6gad2SYVR9Ya822h6mOKI3sSXRnwSGEWBJMnTLsszTZhpbfarnh9cfI9_saN08DbzZF87m6RcSxyqAKoK63o9RsrJWnPd2zdq-5A8MRqUjUNllN6I4BgpQTuU44S7zzHOqQyeJdboDjAKiVor2YK8_nMutL7DQJux-m_KIIYukvnrthumPCbaS9BCbwkB5j8vW0cYZGfPVrXZHqrHrvU7tfsWmY9wf0Onakt7d3AAAA__8.VVE25rQqbrC-isGOqbRTqMPoK4ts5-9_6zSgz0fUg11m9GCClq10PS9u1DlaXye-S2MYYyHVEHSVs6uKcPVvN2WGBHkv7t-c4Hixc9O8zrJYhJaP979wF_gn08YnRlX7_o4Qj6muc1IWHjK0hPMIgq0X-sBU2Git9uppVW1jbLA",
      "tokenType": "BEARER",
      "validity": 86400
  }

Step 2
Create the API key for this user using the JWT created above.

NOTE:
The Authorization header uses the value of the token attribute from the response to the login
request made in the previous step.

curl -X POST https://masterservername:1556/netbackup/security/api-keys           \
     -H 'Content-Type: application/vnd.netbackup+json;version=3.0'                    \
     -H 'Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsInppcCI6IkRFRiJ9.eNp0VF1v2jAU_S9-nHiArXQrb15yaT2cOLIdEJ2mKGWZmnXARMKEVvW_13EciO3weu65H-d-vaIyr9FsMp18Gt_dTsefb6bjESqrCs3Q7umYbfOqLg5ohH7XpYIWqwVfzNM1k6tHvCKJMhSnv63_5MvHO-V_cztC1fFJkQ_b3bGaHar6UGxeitm_k2Lnx_o5q_cvxW44Wlll-c9t2Vjrw7FokW2-eS53hcJ-5X-qwoT5n232u7o4qfJfEQchMZfZN_YVzb6jD-jHSGOMQ0YifA9ndElg5dJAZg9MyDMUcMASsmUkgC-B96jGYrFDoKCwgFEKgSQsPlsoETILgEsyJ4HyE2dLxEIyX9txDJYwSoK1Xa_F01EFZcLnZJgS3MOBNxEhDhNGYi9Tr7KLdJZ4JXBYsgUM0nUtnFFfmirQ7ZBUUZzm6EwEHClDmbTBKczEtacZK55kkXJuwrjcflm6gq45Tgne7I1_o9XF8CNPqdMTnIZEUnYvXLIjQZPnEIoQS2yjAwPVuJLrIFioFfYy4VQ-6JY70hLgERGiv6gad2SYVR9Ya822h6mOKI3sSXRnwSGEWBJMnTLsszTZhpbfarnh9cfI9_saN08DbzZF87m6RcSxyqAKoK63o9RsrJWnPd2zdq-5A8MRqUjUNllN6I4BgpQTuU44S7zzHOqQyeJdboDjAKiVor2YK8_nMutL7DQJux-m_KIIYukvnrthumPCbaS9BCbwkB5j8vW0cYZGfPVrXZHqrHrvU7tfsWmY9wf0Onakt7d3AAAA__8.VVE25rQqbrC-isGOqbRTqMPoK4ts5-9_6zSgz0fUg11m9GCClq10PS9u1DlaXye-S2MYYyHVEHSVs6uKcPVvN2WGBHkv7t-c4Hixc9O8zrJYhJaP979wF_gn08YnRlX7_o4Qj6muc1IWHjK0hPMIgq0X-sBU2Git9uppVW1jbLA' \
     -d '{"data":{"type": "apiKeyCreationRequest","attributes":{"expireAfterDays":"P1D","description":"API key for user myusername with 1 year validity"}}}'

The response contains two attributes apiKey and expiryDateTime.
The apiKey attribute provides the API key for user "myusername".
The expiryDateTime attribute indicates the time until which this API key is valid.

{
    "data": {
        "links": {
            "self": {
                "href": "/netbackup/security/api-keys/A1uMjmj93mo="
            }
        },
        "type": "apiKeyCreationResponse",
        "id": "A1uMjmj93mo=",
        "attributes": {
            "apiKey": "A1uMjmj93mrpsW9qWroT-paNdMSDPdABCEDi7PRPD-Mc0mkFn6-KvHdXT1v8Wxx7",
            "expiryDateTime": "2019-04-25T08:28:30.294Z"
        }
    }
}

Step 3
Get the job information using the NetBackup API endpoint GET /admin/jobs/{jobId}.
In this example, the information for the job ID 5 is requested.

NOTE:
The Authorization header uses the value of the apiKey attribute from the response to the login
request made in the previous step.

curl -X GET https://masterservername:1556/netbackup/admin/jobs/5 \
     -H 'Accept: application/vnd.netbackup+json;version=2.0'     \
     -H 'Authorization: A1uMjmj93mrpsW9qWroT-paNdMSDPdABCEDi7PRPD-Mc0mkFn6-KvHdXT1v8Wxx7'

The response to the GET request contains the job information for job ID 5:

{
    "data": {
...
        "type": "job",
        "id": "5",
        "attributes": {
            "jobId": 5,
            "parentJobId": 0,
            "activeProcessId": 27116,
            "mainProcessId": 0,
            "jobType": "IMAGEDELETE",
            "jobSubType": "IMMEDIATE",
            "policyType": "STANDARD",
            "policyName": "",
            "scheduleType": "FULL",
...
}

SSL certificate validation

The NetBackup web service always sends its certificate during SSL handshakes. This certificate can be validated by the
API client. To validate the certificate, you will need to get the Certificate Authority (CA) certificate from the master
server and then use the CA certificate in the API requests.

TIP:
It is a good practice to validate the SSL certificate. This action ensures that you are communicating with the correct
web service.

Step 1
Get the CA certificate from the master server using the GET /security/cacert API:

NOTE:
You cannot make a secure request with certificate validation until you have the CA certificate. To obtain the initial CA
certificate you must skip the certificate validation, with the "--insecure" curl option.

curl -X GET https://masterservername:1556/netbackup/security/cacert \
     -H 'content-type: application/vnd.netbackup+json;version=2.0'   \
     --insecure

The response to the cacert request contains two certificates:

    {
        "webRootCert": "-----BEGIN CERTIFICATE-----\nMIICljCCAf+gAwIBAgIIcte7aAAAAAAwDQYJKoZIhvcNAQENBQAwTTEOMAwGA1UE\nAxMFbmJhdGQxLjAsBgNVBAsUJXJvb3RAbW9ybGV5dm01LnJtbnVzLnNlbi5zeW1h\nbnRlYy5jb20xCzAJBgNVBAoTAnZ4MB4XDTE4MDEwODE0MjcyNloXDTM4MDEwMzE1\nNDIyNlowTTEOMAwGA1UEAxMFbmJhdGQxLjAsBgNVBAsUJXJvb3RAbW9ybGV5dm01\nLnJtbnVzLnNlbi5zeW1hbnRlYy5jb20xCzAJBgNVBAoTAnZ4MIGfMA0GCSqGSIb3\nDQEBAQUAA4GNADCBiQKBgQDpRc/yo0utxcKrftPeOzn1o1MR5b42uGWrwg9kU4VM\nZN++0kvrtRWt4wz8zdtNU4wtg/MHWt0ffj6FRYYAZBbM8fu56GFux3wCPJSHWl6B\nZ0nD1vZxFUwTXkRAAObuHrYphjBNf1oUU+4GS44KD4/UW/bucKdZsUI1+HcfCQZw\nNwIDAQABo38wfTAPBgNVHRMBAf8EBTADAQH/MAsGAyoDBQQEcm9vdDAPBgMqAwYE\nCDAwMDAwMDE3MC0GAyoDCAQmezg2ZDY5MDU0LWY0OGEtMTFlNy1hNDAyLTYwYWQy\nMTZjYTdlZX0wHQYDVR0OBBYEFE/mpo7PbWs7p/zkAHWi/BDwpdn+MA0GCSqGSIb3\nDQEBDQUAA4GBAAmZJ98XLqG0H+qwyuZ97YdzE2dWKpRduuARYJp437Sc6tpL6nFn\nuzbtGV30tDdhROYPf1AoNRmZHvz40Hra1B8j4VFggPZOAmmk+UJPjzeHn6qhlRxl\nHjCdEqUZ//+1Aqgj6f/6bqPO5boCVP1qw8N60fkBaV3zLwAOY6CKiHS0\n-----END CERTIFICATE-----\n",
        "cacert": [
            "-----BEGIN CERTIFICATE-----\nMIICljCCAf+gAwIBAgIIcte7aAAAAAAwDQYJKoZIhvcNAQENBQAwTTEOMAwGA1UE\nAxMFbmJhdGQxLjAsBgNVBAsUJXJvb3RAbW9ybGV5dm01LnJtbnVzLnNlbi5zeW1h\nbnRlYy5jb20xCzAJBgNVBAoTAnZ4MB4XDTE4MDEwODE0MjcyNloXDTM4MDEwMzE1\nNDIyNlowTTEOMAwGA1UEAxMFbmJhdGQxLjAsBgNVBAsUJXJvb3RAbW9ybGV5dm01\nLnJtbnVzLnNlbi5zeW1hbnRlYy5jb20xCzAJBgNVBAoTAnZ4MIGfMA0GCSqGSIb3\nDQEBAQUAA4GNADCBiQKBgQDpRc/yo0utxcKrftPeOzn1o1MR5b42uGWrwg9kU4VM\nZN++0kvrtRWt4wz8zdtNU4wtg/MHWt0ffj6FRYYAZBbM8fu56GFux3wCPJSHWl6B\nZ0nD1vZxFUwTXkRAAObuHrYphjBNf1oUU+4GS44KD4/UW/bucKdZsUI1+HcfCQZw\nNwIDAQABo38wfTAPBgNVHRMBAf8EBTADAQH/MAsGAyoDBQQEcm9vdDAPBgMqAwYE\nCDAwMDAwMDE3MC0GAyoDCAQmezg2ZDY5MDU0LWY0OGEtMTFlNy1hNDAyLTYwYWQy\nMTZjYTdlZX0wHQYDVR0OBBYEFE/mpo7PbWs7p/zkAHWi/BDwpdn+MA0GCSqGSIb3\nDQEBDQUAA4GBAAmZJ98XLqG0H+qwyuZ97YdzE2dWKpRduuARYJp437Sc6tpL6nFn\nuzbtGV30tDdhROYPf1AoNRmZHvz40Hra1B8j4VFggPZOAmmk+UJPjzeHn6qhlRxl\nHjCdEqUZ//+1Aqgj6f/6bqPO5boCVP1qw8N60fkBaV3zLwAOY6CKiHS0\n-----END CERTIFICATE-----\n"
        ]
    }

Step 2
Save the webRootCert certificate. To do this save the webRootCert string to a file. Make sure to convert the \n
escape sequences to new lines (carriage returns).

For example, your file would look something like this:

Step 3
You can now use the CA certificate in your API requests. For example, to securely use the cacert API remove the
--insecure option and use the --cacert <filename> option. In the following example, the CA certificate was saved in
the file cacert.pem.

curl -X GET https://masterservername:1556/netbackup/security/cacert \
     -H 'content-type: application/vnd.netbackup+json;version=2.0'   \
     --cacert cacert.pem

Authorization

A given NetBackup API may require that one or more Permissions are assigned to a given principal before the request is allowed to run on the server.
In this document, any required permissions for a given resource path are documented in the Description section of the resource as below:

Requires Permission: [Permission value]

When multiple permissions are listed, the enforcement is a logical OR, meaning the principal must have at least one of the expected permissions.
Permissions are granted to a principal through the roles that are assigned in their NetBackup RBAC access rules.

NOTE
Internally, NetBackup uses API Permissions to authorize individual API requests.
A permission is composed of one or more API permissions.
The authorization context for an authorized principal is represented in their JWT and contains one or more API Permission values that are derived from assigned permissions.
However, API Permissions are not exposed to end users for delegation and configuration.

The following table describes the permissions that are assigned to the system-defined roles that are present at installation.

Workload administrator	Backup administrator	Security administrator
Recover/Restore	Manage Jobs	Manage Access Rules
Overwrite Asset	Manage Protection Plans	Manage Global Security Settings
Instant Access	Manage Assets	Manage Certificates
Download Files	Manage NetBackup	View Audit Logs
Restore Files	View Usage Data	Manage Hosts
Manage Assets	Manage SLPs	View Application Servers
	Manage Policies	View Assets
	Manage Application Servers and Asset Groups	View Cloud Application Servers
	Manage Cloud Application Servers	View Protection Plans
	View Recovery Points	Manage API Keys
		View API Keys
		View Domains

Versioning

To maintain compatibility with the back-level API clients, it is sometimes necessary to version the NetBackup API. The
NetBackup API is developed so that new versions are minimized. However, at times changes are needed to the API that
require a new API version. The mechanism to version the NetBackup API is described below.

Version numbers follow a simple MAJOR.MINOR pattern, such as 1.2. These version numbers are not the same as the
NetBackup release number. The current API version number is documented with every NetBackup release. The version number
may not increase sequentially from one NetBackup release to the next release. The version number may increase by
multiple major versions between two consecutive NetBackup releases.

Content negotiation is used to specify which API version the API client is requesting. A new vendor-specific media type
application/vnd.netbackup+json is used, along with a media type parameter named version. For example:
application/vnd.netbackup+json;version=2.0. This media type should be used in the Accept or Content-Type HTTP
header of your request. If you send both Accept and Content-Type HTTP headers, their values must match.

In some cases, an API does not consume any input or produce any output. Such a case normally means that neither Accept
nor Content-Type HTTP headers are required. However, because these headers are used to specify the API version, the
Accept header must be specified.

TIP:
The value of the Content-Type or Accept HTTP header in a NetBackup API request must use this format:
application/vnd.netbackup+media;version=<major>.<minor>

It is important for you to consider the kind of changes that will require a new version of the NetBackup API. Developing
your API client with these rules in mind will ensure that your API client remains compatible with the future versions of
the NetBackup API.

The following is a list of possible API changes and if they result in a new API version:

API change results in a new version?	Yes / No
Add a new endpoint	No
Remove an endpoint	Yes
Add an output field or attribute	No
Remove output field or attribute	Yes
Add required input field or attribute	Yes
Add non-required input field or attribute	No

NOTE:

If the API client expects a particular endpoint or field in the NetBackup response, then removing the endpoint or
field results in a new version.

If NetBackup expects a new required field in the request from the API client, then adding it results in a new
version.

As you develop your API client, as a best practice you should ignore any new fields that are returned to you. Do not
treat unrecognized fields as an error. This way your API clients can continue to work with future releases of NetBackup
without any change.

Pagination

Some NetBackup APIs use pagination to limit the number of resources returned in a response. These APIs use the
page[offset] and page[limit] query parameters to set the starting point (offset) and the page size (limit). The
results are returned in a page-by-page format.

TIP:
The default page size is 10 resources. The type of resource depends on the individual API. For example: For the API
that gets a list of jobs, the page contains job-related information for up to 10 NetBackup jobs.

Filtering

Some NetBackup APIs use the 'filter' query parameter to limit or reduce the number of resources that the response
returns.

Use the OASIS syntax to specify the value of the filter using OData filtering language:
http://docs.oasis-open.org/odata/odata/v4.01/csprd01/part2-url-conventions/odata-v4.01-csprd01-part2-url-conventions.html#_Filter_System_Query.

NOTE:
The supported OData operators and functions depend on each individual NetBackup API, as described in the NetBackup API
reference.

Date and time formatting

All NetBackup APIs accept and return date and time values using the ISO 8601 format in UTC with the Z zone designator.

More information on the details of the ISO spec can be found in the Wikipedia article, "ISO 8601":
https://en.wikipedia.org/wiki/ISO_8601.

About request header X-Client-ID

Veritas recommends that you set the X-Client-ID HTTP request header which mentions
the identity of the consumer component. For example, you can set this HTTP request header
value to customer_id-component_name_calling_the_NB_APIs. Please note that this value won't be
used for any other purposes than telemetry analysis of NetBackup APIs usage. This header value enables
Veritas NetBackup to understand API usage pattern and might help Veritas make improvements in the most frequently used APIs.

About request header X-Request-ID

You can set the request header X-Request-ID while making API calls. This header's value normally is a
UUID, which is tied to the given request, but it can be any random string. This value can be used by NetBackup APIs
to track the request across multiple NetBackup sub-components (other NetBackup processes) if the API implementation
requires communication with other NetBackup components. If you do not mention this value,
the NetBackup API server generates a secure random string and returns this value in X-Request-ID response header.
Veritas recommends that API consumers log this request identifier in order to help track a single request end-to-end,
which helps in troubleshooting issues with APIs.

About encoding requests

All request URLs of NetBackup APIs must be percent encoded according to the RFC3986.
The following aspects need to be taken care of when percent encoding.

Percent encode all URL path parameters
Percent encode all query paramters names and values

Here is an example with query parameters:
A request to GET all assets using a query filter to return only virtual machines where the cluster name begins with Name-à !@#$%^&*.
Additionally, this request is specifying a page offset of 3 and page limit of 9.

Intended Request
GET https://master.nb.com/netbackup/assets?filter=startswith(extendedAttributes/cluster,'Name-à !@#$%^&*')&page[limit]=9&page[offset]=3

should be encoded like below. Note the encoding for query parameters name and value.

Encoded Request
GET https://master.nb.com/netbackup/assets?filter=startswith(extendedAttributes%2Fcluster,'Name-%C3%A0%20!%40%23%24%25%5E%26*')&page%5Blimit%5D=9&page%5Boffset%5D=3

A sample cURL request for the above looks like this

curl --request GET \
  --url "https://master.nb.com/netbackup/assets?filter=startswith(extendedAttributes%2Fcluster%2C'Name-%C3%A0%2040%23%24%25%5E%26*')&page%5Blimit%5D=9&page%5Boffset%5D=3" \
  --header "accept: application/vnd.netbackup+json;version=3.0" \
  --header "authorization: <authorization-token>"

API Code Samples

To hit the ground running with the NetBackup API, you can refer to the API code samples in different programming
languages. The API code samples are located on GitHub: https://github.com/VeritasOS/netbackup-api-code-samples. This is
a community-supported, open source project available under the MIT license.

Disclaimer:

The API code samples are not officially supported by Veritas and should not be used in a production environment.

The purpose of these code samples is only to serve as a reference, to help you write your own applications using the
NetBackup API.

What's New in NetBackup 8.2?

Versioned APIs

This is a list of APIs that have been versioned in 8.2. The previous version of these APIs is still supported by
specifying the correct version. See the Versioning section above for more details.

GET /admin/jobs
GET /admin/jobs/{jobId}
GET /admin/jobs/{jobId}/try-logs
POST /config/slps
PATCH /config/slps/{slpName}
GET /config/snapshotproviders/supportedplugins
GET /config/snapshotproviders/supportedplugins/{pluginType}
POST /config/snapshotproviders/configuredplugins/{pluginType}/instances
PUT /config/snapshotproviders/configuredplugins/{pluginType}/instances/{instanceName}
GET /config/hosts
POST /preview-asset-group
POST /recovery/workloads/vmware/instant-access-mounts
GET /recovery/workloads/vmware/instant-access-mounts
GET /recovery/workloads/vmware/instant-access-mounts/{mountId}
POST /recovery/workloads/vmware/instant-access-mounts/{mountId}/restore
POST /recovery/workloads/vmware/instant-access-vms
GET /recovery/workloads/vmware/instant-access-vms
GET /recovery/workloads/vmware/instant-access-vms/{mountId}
POST /servicecatalog/slos
GET /servicecatalog/slos
GET /servicecatalog/slos/{sloId}
PUT /servicecatalog/slos/{sloId}
PATCH /servicecatalog/slos/{sloId}
DELETE /servicecatalog/slos/{sloId}
GET /storage/storage-units
GET /storage/storage-units/{storageUnitName}

New APIs

Jobs API: Includes progress logs and individual try logs
Discover Now: Provides the ability to manually initiate discovery on a vCenter or RHV managers
Images API: Provides the ability to browse content, manage expiration, change primary copy, fast import for
CloudCatalyst
VM Server Credential Management: Provides the ability to verify and delete credentials
VM Server Configuration Management: Includes resource limits and proxy host configuration
Common Access Card (CAC) and Personal Identity Verification (PIV): Provides the ability to authenticate by user
certificate
User Session Management: Compliant with Defense Information Systems Agency Security Technical Implementation
Guides (DISA STIGs)
API Keys: API authentication management
Storage Management: Create, read, update, and delete (CRUD) operations on disk and cloud STUs, disk pools, cloud
storage pools, and MSDP replication topology management
NetBackup Configuration Management: Lists running processes and daemons. Also read and update configuration
similar to bpgetconfig and bpsetconfig
Manual Backup: Performs bpbackup operations on existing policies

New request header X-Client-ID

Please see the About request header X-Client-ID section above.

New request header X-Request-ID

Please see the About request header X-Request-ID section above.

API Documentation on Master Server

The NetBackup API documentation is now available directly on the master server using the Swagger UI for presentation.
This enables API testing using the Try It Out button. Please note that using this functionality makes real API calls
to your Master Server.

NOTE:
While all the standard security and authorization checks are enforced, it is possible to make
destructive calls using this tool. It is recommended that this be used in a development environment.

The documentation can be found at the following URL: https://<master_server>/api-docs/index.html

NetBackup™ 8.2 API - Getting Started