Skip to content

RestfulAPI (CDMI)

Jump to bottom Edit New page
femiadeyemi edited this page Oct 5, 2016 · 57 revisions
Common task HTTP method (by path) Status
Get the list of Quality of Services (QoS) for a file GET /api/v1/qos-management/qos/file Test
Get the list of QoS for a directory GET /api/v1/qos-management /qos/directory Test
Get data describing a specific QoS for a file GET /api/v1/qos-management/qos/file/{disk/tape/disk+tape} Test
Get data describing a specific QoS for a directory GET /api/v1/qos-management/qos/directory/{tape/disk} Test
Get Current QoS Status for file GET /api/v1/qos-management/namespace/{path} Test
Update QoS for the specified Object POST /api/v1/qos-management/namespace/{path} on RB
Get Current QoS Status for directory GET /api/v1/qos-management/namespace/{path}

Status: Implemented, Test, Production

1. Get list of Quality of Services for file objects.

Get the list of available QoS for file objects corresponding to some specific quality of services supported by dCache back-end. For example, storage requirements such as flexible allocation of disk or tape storage space.

Prerequisites

...

HTTP request

GET /api/v1/qos-management/qos/file
Request headers

....

Response headers

Content-Type: application/json
Response message body

name Value Description Requirement
status String "200" Mandatory
message String "successful" Mandatory
name String List of available QoS Optional
Response status

name Value Description
status String "200"
error String "successful"
Error Response

  • The user is not authorized
name Value Description
status String "401"
error String "Permission denied"
  • Internal Server Error
name Value Description
status String "500"
error String "Internal Server Error"
Example
GET api/v1/qos-management/qos/file   HTTP/1.1

The following shows successful response:

HTTP/1.1 200 OK
Content-Type: application/json


{
   "status" : "200",
   "message" : "successful",
   "name" : ["DISK", "TAPE", "DISK + TAPE"]
}

The following shows error response:

{
   "status" : "401",
   "error"  : "Permission denied"
}

1.1. Get list of Quality of Services for directory objects.

Get the list of available QoS for directory objects corresponding to some specific quality of services supported by dCache back-end.

Prerequisites

...

HTTP request

GET /api/v1/qos-management/qos/directory
Request headers

....

Response headers

Content-Type: application/json
Response message body

name Value Description Requirement
status String "200" Mandatory
message String "successful" Mandatory
name String List of available QoS: "disk" or "tape" Optional
Response status

name Value Description
status String "200"
error String "successful"
Error Response

  • The user is not authorized
name Value Description
status String "401"
error String "Permission denied"
  • Internal Server Error
name Value Description
status String "500"
error String "Internal Server Error"

Example
GET api/v1/qos-management/qos/directory   HTTP/1.1

The following shows successful response:

HTTP/1.1 200 OK
Content-Type: application/json


{
   "status" : "200",
   "message" : "successful",
   "name" : ["DISK", "TAPE"]
}

The following shows error response:

{
   "status" : "401",
   "error"  : "Permission denied"
}

2. Get data describing a specific QoS for a file.

All QoS objects for file objects are specified by "name", "transition" attributes. If present, the QoS objects should also contain data system metadata values which are described in the following sections.

Prerequisites

The user must have granted access. ????

HTTP request
GET /api/v1/qos-management/qos/file/{disk|tape|disk+tape}
Request headers

....

Response headers

....

Response Object
Name Type Description Requirement
status String HTTP status code number Mandatory
message String Text describing whether the call was successful or not. Optional
error String Text describing the reason of exception or error. Optional
backendCapability JSON Object Data describing specific QoS. Optional
backendCapability Object
backendCapability Type Description Requirement
name String The name of a qos. For example storage requirements such as flexible allocation of DISK or TAPE, or both DISK + TAPE storage space. Optional
metadata JSON Object Data describing specific qos, please see CDMI specification for more details. ???
transition Array Indicates possible transition status, for example, user might want to change the QoS for the stored objects. Optional

CDMI specification is provided here: https://docs.google.com/document/d/1ovUl8G1SyyAX_pBaiEu7Yu34Vxnc3-sjvPuXIu6E1MM/edit#heading=h.ol78x7m3e19g.

Provided values of metadata items.
metadata Type Description Requirement
cdmi_data_redundancy_provided String The number of copies. Optional
cdmi_geographic_placement_provided Array of Strings Geolocation Optional
cdmi_latency_provided String Maximum time to first byte in milliseconds Optional
Prerequisites

The user must have granted access. ????

Example

Get data describing "DISK" QoS.

GET /api/v1/qos-management/qos/file/disk HTTP/1.1
Response message body


HTTP/1.1 200 OK
Content-Type: application/json

{
  "status" : "200",
  "message" : "successful"
  "backendCapability" : 
  {
   "name" : "DISK",
   "metadata" : {
        "cdmi_data_redundancy_provided" : "1",
        "cdmi_geographic_placement_provided": "DE",
        "cdmi_latency_provided" : "100"
        }
   "transition" : [ ]
  }

Get data describing "TAPE" QoS.

GET /api/v1/qos-management/qos/file/tape HTTP/1.1
Response message body

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status" : "200",
  "message" : "successful"
  "backendCapability" : 
  "name" : "TAPE",
  "metadata" : {
      "cdmi_data_redundancy_provided" : "1",
      "cdmi_geographic_placement_provided": "DE",
      "cdmi_latency_provided" : "600000"
       }
 "transition" : ["DISK + TAPE"]
}

Get data describing "DISK + TAPE" QoS.

GET /api/v1/qos-management/qos/file/disk+tape  HTTP/1.1
Response message body

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status" : "200",
  "message" : "successful"
  "backendCapability" : {
          "name" : "DISK + TAPE",
          "metadata" : {
              "cdmi_data_redundancy_provided" : "2",
              "cdmi_geographic_placement_provided": "DE",
              "cdmi_latency_provided" : "100"
               }
          "transition" : ["TAPE"]
          }

}
Response status

name Description
status String "200"
message String "successful"
Error Response status

  • The user is not authorized to make this transition.
name Value Description
status String "401"
error String "Permission denied"
  • The QoS is not known or supported.
name Value Description
status String "404"
error String "Not supported"
  • The path does not exist.
name Value Description
status String "404"
error String "Bad Request"
  • Internal Server Error
name Value Description
status String "500"
error String "internal Server Error"

2.2 Get data describing a specific QoS for a directory.

The two currently available QoS for directories are described using the same attributes, with the only difference of the "transition" attribute.

backendCapability Object
backendCapability Type Description Requirement
name String The name of a qos. For example storage requirements such as flexible allocation of DISK or TAPE, or both DISK + TAPE storage space. Optional
metadata JSON Object Data describing specific qos, please see CDMI specification for more details. ???
transition Array Indicates possible transition status, for example, user might want to change the QoS for the stored objects. Only transitions "Tape to Disk" and "Disk to Tape" are available Optional
Prerequisites

The user must have granted access. ????

HTTP request
GET /api/v1/qos-management/qos/directory/{disk|tape}
Request headers

....

Response headers

....

Response Object

.....

Prerequisites

The user must have granted access. ????

Example

Get data describing "DISK" QoS.

GET /api/v1/qos-management/qos/directory/disk HTTP/1.1
Response message body


HTTP/1.1 200 OK
Content-Type: application/json

{
  "status" : "200",
  "message" : "successful"
  "backendCapability" : 
  {
   "name" : "DISK",
   "metadata" : {
        "cdmi_data_redundancy_provided" : "1",
        "cdmi_geographic_placement_provided": "DE",
        "cdmi_latency_provided" : "100"
        }
   "transition" : [ "TAPE"]
  }

Get data describing "TAPE" QoS.

GET /api/v1/qos-management/qos/directory/tape HTTP/1.1
Response message body

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status" : "200",
  "message" : "successful"
  "backendCapability" : 
  "name" : "TAPE",
  "metadata" : {
      "cdmi_data_redundancy_provided" : "1",
      "cdmi_geographic_placement_provided": "DE",
      "cdmi_latency_provided" : "600000"
       }
 "transition" : ["DISK"]
}
Response status

name Description
status String "200"
message String "successful"
Error Response status

  • The user is not authorized to make this transition.
name Value Description
status String "401"
error String "Permission denied"
  • The QoS is not known or supported.
name Value Description
status String "404"
error String "Not supported"
  • The path does not exist.
name Value Description
status String "404"
error String "Bad Request"
  • Internal Server Error
name Value Description
status String "500"
error String "internal Server Error"

Get Current Status

Gets the current status of the object, (including transition status), for the object specified by path.

Prerequisites

The user must have granted read access to the specified item. ????

HTTP request
GET /avi/v1/qos-management/namespace/{path}
Request headers

....

Response headers

....

Response message body

Response body returns JSON object described by the following structures.

name Value Description Requirement
status String "200" Mandatory
message String "successful" Mandatory
Example
GET /api/v1/qos-management/qos/myFolder/myFile  HTTP/1.1

The following shows successful response:


HTTP/1.1 200 OK
Content-Type: application/json

{
"status" : "200",
"message" : "successful",
"qos" : "TAPE"

}

When the QoS of a file is in transitional status the following response will be returned:


HTTP/1.1 200 OK
Content-Type: application/json

{
"status" : "200",
"message" : "successful",
"qos" : "TAPE"
"update" : "DISK+TAPE"

}
Error Response status

  • The user is not authorized to make this transition
name Value Description
status String "401"
error String "Permission denied"
  • The specified QoS is not known/supported
name Value Description
status String "404"
error String "Not supported"
  • The specific transition is not supported
name Value Description
status String "400"
error String "Not known"
  • The path does not exist
name Value Description
status String "404"
error String "Not Found"
  • Internal Server Error
name Value Description
status String "500"
error String "internal Server Error"

Update CDMI Object

Starts a object transition to the specified QoS. ????

Prerequisites

The user must have granted read access to the specified item. ????

HTTP request
POST /api/v1/qos-management/namespace/{path}
Request headers

Accept: application/json
Content-Type: application/json
Response headers

....

Request message body
{

"update" : "TAPE"
}

where qos is transition status from one qos to another.

List of possible transition states are given in the following table.

qos current state transition
DISK TAPE DISK + TAPE
TAPE DISK + TAPE TAPE
Response message body
name Description
status String "200"
message String "successful"
Error Response

  • The user is not authorized to make this transition
name Value Description
status String "401"
error String "Permission denied"
  • The specified QoS is not known/supported
name Value Description
status String "404"
error String "Not supported"
  • The specific transition is not supported
name Value Description
status String "501"
error String "Not Implemented"
  • The path does not exist
name Value Description
status String "404"
error String "Not Found"
  • Internal Server Error
name Value Description
status String "500"
error String "internal Server Error"
Example
 
POST  /api/v1/qos-management/namespace/{path}/  HTTP/1.1
Accept: application/json
Content-Type: application/json

The following shows successful response:


HTTP/1.1 200 OK
Content-Type: application/json

{
"status" : "200"
"message" : "Transition was successful"
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally