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 . Enter username and password. Click on .
This will return a token, userRole and warning in Response body 200.
Copy the token from Response body.
Step 2: Authorization
Click on in the upper right corner of Swagger UI. This will open a popup modal. In the 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 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 and then click . 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 . Enter the file system name in the input box and then . 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