Search <book_title>...

Veritas Access Appliance Administrator's Guide

Last Published: 2023-10-29

Product(s): Appliances (8.0)

Platform: Access Appliance OS,Veritas 3340,Veritas 3350

Getting started with Access Appliance APIs

The Access Appliance API provides a web-service based interface to manage and administer the Veritas Access Appliance server. The Access Appliance API is built on the Representational State Transfer (REST) architecture, which is the most widely used style for building APIs. The Access Appliance API uses the HTTP protocol to communicate with the Access Appliance server. It is easy to use in cloud-based applications, as well as across multiple platforms and programming languages.

The Access Appliance API uses JavaScript Object Notation (JSON) as the message format for the request and response messages. It 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 Access Appliance server. The server processes the request and 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.

The Access Appliance server authenticates the incoming API requests based on a JSON Web Token (JWT) 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. The login API accepts a username and password. The port that is used to access the Access Appliance API is the standard Access Appliance PBX port, 14161.

Example of generating and using JWT for authentication

The following procedure provides a sample workflow to retrieve task information from Access Appliance server. This procedure involves logging in to Access Appliance server to receive a JWT and then requesting task information for a specific task (task ID f42ac680-acba-11ea-b342-1f3ab58ec019 in this scenario).

Step 1:

Use the Access Appliance API endpoint POST /api/appliance/v1.0/authentication/login to create a login request:

curl --cookie-jar /tmp/cookies.txt -g -k -X POST 
https://hostname:14161/api/appliance/v1.0/authentication/login\
--header 'Accept: application/json'\  
--header 'Content-Type: application/x-www-form-urlencoded'\
 --data 'userName=myuser&password=mypassword'

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

The userRole attribute indicates the Role of the user.

{
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsInppcCI6IkRFRiJ9.
eNp0VF1v2jAU_S9-nHiArXQrb15yaT2cOLIdEJ2mKGWZmnXARMKEVvW_13EciO3weu65H
-d-vaIyr9FsMp18Gt_dTsefb6bjESqrCs3Q7umYbfOqLg5ohH7XpYIWqwVfzNM1k6tHvCK
JMhSnv63_5MvHO-V_cztC1fFJkQ_b3bGaHar6UGxeitm_k2Lnx_o5q_cvxW44Wlll-c9t2V
jrw7FokW2-eS53hcJ-5X-qwoT5n232u7o4qfJfEQchMZfZN_YVzb6jD-jHSGOMQ0YifA9nd
Elg5dJAZg9MyDMUcMASsmUkgC-96jGYrFDoKCwgFEKgSQsPlsoETILgEsyJ4HyE2dLxEIyX
9txDJYwSoK1Xa_F01EFZcLnZJgS3MOBNxEhDhNGYi9Tr7KLdJZ4JXBYsgUM0nUtnFFfmirQ
7ZBUUZzm6EwEHClDmbTBKczEtacZK55kkXJuwrjcflm6gq45Tgne7I1_o9XF8CNPqdMTnIZE
UnYvXLIjQZPnEIoQS2yjAwPVuJLrIFioFfYy4VQ-6JY70hLgERGiv6gad2SYVR9Ya822h6m
OKI3sSXRnwSGEWBJMnTLsszTZhpbfarnh9cfI9_saN08DbzZF87m6RcSxyqAKoK63o9Rsr
JWnPd2zdq-5A8MRqUjUNllN6I4BgpQTuU44S7zzHOqQyeJdboDjAKiVor2YK8_nMutL7DQ
Jux-m_KIIYukvnrthumPCbaS9BCbwkB5j8vW0cYZGfPVrXZHqrHrvU7tfsWmY9wf0Onakt
7d3AAAA__8.VVE25rQqbrC-isGOqbRTqMPoK4ts5-9_6zSgz0fUg11m9GCClq10PS9u1D
laXye-S2MYYyHVEHSVs6uKcPVvN2WGBHkv7t-c4Hixc9O8zrJYhJaP979wF_gn08YnRlX
7_o4Qj6muc1IWHjK0hPMIgq0X-sBU2Git9uppVW1jbLA",
      "userRole": "Appliance Administrator"
  }

Step 2:

Get the task information using the Access Appliance API endpoint GET /api/appliance/v1.0/tasks/{taskId}. In this example, the information for the task ID f42ac680-acba-11ea-b342-1f3ab58ec019 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 --cookie /tmp/cookies.txt -k -X GET 
https://hostname:14161/api/appliance/v1.0/tasks/f42ac680-acba-11ea-
b342-1f3ab58ec019     \
     --header 'Accept: application/json'                                                                                          \
     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz
I1NiIsInppcCI6IkRFRiJ9.eNp0VF1v2jAU_S9-nHiArXQrb15yaT2cOLIdEJ2mKGWZmnX
ARMKEVvW_13EciO3weu65H-d-vaIyr9FsMp18Gt_dTsefb6bjESqrCs3Q7umYbfOqLg5oh
H7XpYIWqwVfzNM1k6tHvCKJMhSnv63_5MvHO-V_cztC1fFJkQ_b3bGaHar6UGxeitm_k2
Lnx_o5q_cvxW44Wlll-c9t2Vjrw7FokW2-eS53hcJ-5X-qwoT5n232u7o4qfJfEQchMZfZ
N_YVzb6jD-jHSGOMQ0YifA9ndElg5dJAZg9MyDMUcMASsmUkgC-96jGYrFDoKCwgFEKgS
QsPlsoETILgEsyJ4HyE2dLxEIyX9txDJYwSoK1Xa_F01EFZcLnZJgS3MOBNxEhDhNGYi
9Tr7KLdJZ4JXBYsgUM0nUtnFFfmirQ7ZBUUZzm6EwEHClDmbTBKczEtacZK55kkXJuw
rjcflm6gq45Tgne7I1_o9XF8CNPqdMTnIZEUnYvXLIjQZPnEIoQS2yjAwPVuJLrIFi
oFfYy4VQ-6JY70hLgERGiv6gad2SYVR9Ya822h6mOKI3sSXRnwSGEWBJMnTLsszTZh
pbfarnh9cfI9_saN08DbzZF87m6RcSxyqAKoK63o9RsrJWnPd2zdq-5A8MRqUjUNl
lN6I4BgpQTuU44S7zzHOqQyeJdboDjAKiVor2YK8_nMutL7DQJux-m_KIIYukvnr
thumPCbaS9BCbwkB5j8vW0cYZGfPVrXZHqrHrvU7tfsWmY9wf0Onakt7d3AAAA__
8.VVE25rQqbrC-isGOqbRTqMPoK4ts5-9_6zSgz0fUg11m9GCClq10PS9u1Dla
Xye-S2MYYyHVEHSVs6uKcPVvN2WGBHkv7t-c4Hixc9O8zrJYhJaP979wF_gn
08YnRlX7_o4Qj6muc1IWHjK0hPMIgq0X-sBU2Git9uppVW1jbLA'

The response to the GET request contains the task information for task ID f42ac680-acba-11ea-b342-1f3ab58ec019:

{
    "data": {
        "links": {
            "self": {
                "href": "/api/appliance/v1.0/tasks/f42ac680-acba-
																								11ea-b342-1f3ab58ec019"
            }
        },
        "type": "tasks",
        "id": "1",
        "attributes": {
            "isParent": true,
            "numCompleted: 1,
            "state": "SUCCESS",
            "taskId": "f42ac680-acba-11ea-b342-1f3ab58ec019",
            "source": "MASTER_FS",
            "numChildren: 2,
            "parentTaskId": "Unknown",
            "progress": "Unknown",
            "userName": "Unknown",
            "startTime": "2020-06-12 14:42:35",
            "sourceType": "vrts_raidgroup",
            "taskName": "Create File System MASTER_FS",
            "endTime": 2020-06-12 14:43:39,
            "output": [\"ACCESS fs SUCCESS V-493-10-2110 Created 
																						mirrored file system MASTER_FS\"],
            "childrenTaskIdList": ["f7d750fa-acba-11ea-a760-000c29
																						1f5977","035d1158-acbb-11ea-9ea1-000c291f5977"]
        }
    }
}

Executing the REST APIs through Swagger UI

Swagger UI link: https://hostname:14161/swagger

Step 1: Authentication
- Click on POST /api/appliance/v1.0/authentication/login
- Click on Try it out. Enter username and password. Click on Execute.
- This will return a token, userRole and warning in Response body 200.
- Copy the token from Response body.

Step 2: Authorization

Click on Authorize in the upper right corner of Swagger UI. This will open a popup modal. In the Value field, type Bearer (space) and paste the token copied in the previous step 1.

Example: Bearer

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOi
I5OWU5ZGRlMzky NWIiLCJpYXQiOjE2NDk5MzQyMDZ9.Eyv2lmRz7pM__PL
UdgkyevuV8dM78-ie65rr5xzVgcshWS25HuN7bmELscNIIC13n1EKILb953ne
BfW_o9R9RA8IalmL_m6NsBvNWb6AfXbAFxVXHRAPAZnDpkkt6hls6koONkC0Ld
I1707w7wrceZMgWMe-F8cGmffN3dSiCvG89JkSLOwL0K6gQNcwqkkzJnI5S7by
R_YMrB5hbgWV2zJMbWIIwAJoGChWE2uhhGobKqztxo0Y1ZN-XrCk4E_AFtLrbZ
4GjO_AddvbpYcV1Q7DdCZsKgSMpHG5N8FFwDtk3n_8zriVV0XPLnMGMadbSM
9qm5YmO-MkuydSI07KlQ

Click on Authorize and close the popup modal.

Step 3: Execute REST APIs

To get all the file systems using the Access Appliance API, click on GET /api/appliance/v1.0/storage/filesystems. Click on Try it out and then click Execute. This will return a list of file systems in Response body 200.

{
  "links": {
    "self": {
      "href": "/api/appliance/v1.0/storage/filesystems"
    }
  },
  "data": [
    {
      "links": {
        "self": {
          "href": "/api/appliance/v1.0/storage/filesystems/fs1"
        }
      },
      "type": "storage",
      "id": "1"
    },
    {
      "links": {
        "self": {
          "href": "/api/appliance/v1.0/storage/filesystems/fs2"
        }
      },
      "type": "storage",
      "id": "1"
    }
  ]
}

To get the specific file system information using the Access Appliance API, click on GET /api/appliance/v1.0/tasks/{fsName}. In this example, the information for file system name is requested.

Click on Try it out. Enter the file system name in the input box and then Execute. This will return details of the requested file system in Response body 200.

{
  "links": {
    "self": {
      "href": "/api/appliance/v1.0/storage/filesystems/fs1"
    }
  },
  "data": {
    "links": {
      "self": {
        "href": "/api/appliance/v1.0/storage/filesystems/fs1"
      }
    },
    "type": "storage",
    "id": "1",
    "attributes": {
      "fsBlockSize": 8192,
      "size": "1.00 GB",
      "usedSize": "49.30 MB",
      "fullFsckStatus": "Not Running",
      "fullFsck": 0,
      "isDedupeEnabled": "No",
      "storageLayout": "striped",
      "numColumn": "5",
      "resiliency": "-",
      "fsName": "fs1",
      "offlineNodeNameList": [],
      "onlineNodeNameList": [
        "r6515-003v011",
        "r6515-003v012"
      ],
      "status": "online",
      "stripeUnit": "64 K",
      "isWormEnabled": "No",
      "reconfigState": "Unknown",
      "isReconfigRunning": false,
      "minimumRetention": "",
      "maximumRetention": "",
      "diskPoolName": "pool_default",
      "diskNameList": [
        "vrts_appliances0_4",
        "vrts_appliances0_6",
        "vrts_appliances0_7",
        "vrts_appliances0_8",
        "vrts_appliances0_9"
      ],
      "fsId": "{2d2c9fed-7620-9bd8-d298-c74bcc50a140}_fs1",
      "usage": []
    }
  }
}

Possible response codes an Access Appliance API can return:

200 - Successful
400 - Error: Bad Request
401 - Error: Unauthorized
500 - Error: Internal Server Error