Storage Gateways

The Storage Gateway API allows administrators to manage storage gateways, and also allows Globus users to determine what storage gateways they may use to create Guest Collections.

Each Storage Gateway contains information about the connector it interfaces with as well as policies that determine who may manage or access collections on the Storage Gateway as well as how that Storage Gateway interacts with the connector.

Operations which modify a storage gateway, or inspect private policies require an administrator role.

Overview

Method	API Path	Description
`GET`	/storage_gateways	Get Storage Gateways
`POST`	/storage_gateways	Create Storage Gateway

Overview

Method	API Path	Description
`GET`	/storage_gateways/{storage_gateway_id}	Get a Storage Gateway
`DELETE`	/storage_gateways/{storage_gateway_id}	Delete Storage Gateway
`PATCH`	/storage_gateways/{storage_gateway_id}	Update a Storage Gateway
`PUT`	/storage_gateways/{storage_gateway_id}	Update a Storage Gateway

Common Path Parameters

Parameter	Type	Description
storage_gateway_id (required)	string Any	ID of the Storage Gateway.

Details

Get Storage Gateways

GET /storage_gateways

Get the Endpoint’s list of StorageGateway documents.

The include query parameter controls what additional information is included in the Result document.

This operation requires either the endpoint to have the public property set to true, the caller to have a role that allows viewing this Endpoint, the user to have an identity which is allowed by the individual Storage Gateway policies, or an identity which has an ACL for a collection created on this Storage Gateway.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator, endpoint:activity_manager, endpoint:activity_monitor, collection:administrator:{collection_id}, collection:activity_manager:{collection_id}, collection:activity_monitor:{collection_id}, collection:access_manager:{collection_id} ]
CollectionACLAuthorizer: [ {collection_id} ]
StorageGatewayAuthorizer [ {storage_gateway_id} ]

Query Parameters

Parameter	Type	Description
include	array(string) `private_policies`	List of document types to include in the response. If `private_policies` is in the list, then include private storage gateway policies in the attached storage_gateways document. This requires an `administrator` role on the Endpoint.
marker	string Any	Pagination marker for a paginated response

Responses

200 - Get Storage Gateways result

Table 1. application/json
Name	Type	Description
code	string `success`
data	array ( StorageGateway )	List of Storage Gateway documents.
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "data": [
    {
      "id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
      "display_name": "Posix Storage Gateway",
      "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
      "high_assurance": true,
      "require_high_assurance": true,
      "authentication_timeout_mins": 30,
      "authentication_assurance_timeout": 30,
      "allowed_domains": [
        "example.com"
      ],
      "identity_mappings": [
        {
          "DATA_TYPE": "external_identity_mapping#1.0.0",
          "command": [
            "/opt/globus/bin/python",
            "/opt/globus/map-globus-identity-data"
          ]
        }
      ],
      "users_allow": [
        "user1"
      ],
      "users_deny": [
        "user2"
      ],
      "restrict_paths": {
        "DATA_TYPE": "path_restrictions#1.0.0",
        "read": [
          "/public"
        ],
        "read_write": [
          "/home",
          "/projects"
        ],
        "none": [
          "/private"
        ]
      },
      "process_user": "gcsweb",
      "load_dsi_module": "google_drive",
      "policies": {
        "DATA_TYPE": "blackpearl_storage_policies#1.0.0",
        "s3_endpoint": "http://blackpearl.example.org:8080",
        "bp_access_id_file": "/etc/blackpearl/access-id-file"
      },
      "DATA_TYPE": "storage_gateway#1.0.0"
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}

400 - Bad request

401 - Unauthorized

403 - Permission Denied

Create Storage Gateway

POST /storage_gateways

Create a StorageGateway on the Endpoint. On success, this operation returns a copy of the created Storage Gateway with the system generated id added.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Request body

application/json

A storage gateway provides the access policies for the endpoint’s connected storage systems. It is a named interface by which authorized users can create and manage collections on the connected storage system. A single storage system may be associated with multiple storage gateways, each with its own policies.

Storage gateway policies describe what type connector the storage gateway uses, the paths it allows access to, the login requirements are for the storage gateway, and the algorithm to map Globus identities to the user namespace of the storage gateway (e.g. local accounts).

Name	Type	Description
body	StorageGateway One of { StorageGateway 1.0.0 , StorageGateway 1.1.0 }	A storage gateway provides the access policies for the endpoint’s connected storage systems. It is a named interface by which authorized users can create and manage collections on the connected storage system. A single storage system may be associated with multiple storage gateways, each with its own policies. Storage gateway policies describe what type connector the storage gateway uses, the paths it allows access to, the login requirements are for the storage gateway, and the algorithm to map Globus identities to the user namespace of the storage gateway (e.g. local accounts).

Example

{
  "id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
  "display_name": "Posix Storage Gateway",
  "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
  "high_assurance": true,
  "require_high_assurance": true,
  "authentication_timeout_mins": 30,
  "authentication_assurance_timeout": 30,
  "allowed_domains": [
    "example.com"
  ],
  "identity_mappings": [
    {
      "DATA_TYPE": "external_identity_mapping#1.0.0",
      "command": [
        "/opt/globus/bin/python",
        "/opt/globus/map-globus-identity-data"
      ]
    }
  ],
  "users_allow": [
    "user1"
  ],
  "users_deny": [
    "user2"
  ],
  "restrict_paths": {
    "DATA_TYPE": "path_restrictions#1.0.0",
    "read": [
      "/public"
    ],
    "read_write": [
      "/home",
      "/projects"
    ],
    "none": [
      "/private"
    ]
  },
  "process_user": "gcsweb",
  "load_dsi_module": "google_drive",
  "policies": {
    "DATA_TYPE": "blackpearl_storage_policies#1.0.0",
    "s3_endpoint": "http://blackpearl.example.org:8080",
    "bp_access_id_file": "/etc/blackpearl/access-id-file"
  },
  "DATA_TYPE": "storage_gateway#1.0.0"
}

Responses

200 - Create Storage Gateway result

Table 2. application/json
Name	Type	Description
code	string `success`
data	array ( StorageGateway )
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "data": [
    {
      "id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
      "display_name": "Posix Storage Gateway",
      "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
      "high_assurance": true,
      "require_high_assurance": true,
      "authentication_timeout_mins": 30,
      "authentication_assurance_timeout": 30,
      "allowed_domains": [
        "example.com"
      ],
      "identity_mappings": [
        {
          "DATA_TYPE": "external_identity_mapping#1.0.0",
          "command": [
            "/opt/globus/bin/python",
            "/opt/globus/map-globus-identity-data"
          ]
        }
      ],
      "users_allow": [
        "user1"
      ],
      "users_deny": [
        "user2"
      ],
      "restrict_paths": {
        "DATA_TYPE": "path_restrictions#1.0.0",
        "read": [
          "/public"
        ],
        "read_write": [
          "/home",
          "/projects"
        ],
        "none": [
          "/private"
        ]
      },
      "process_user": "gcsweb",
      "load_dsi_module": "google_drive",
      "policies": {
        "DATA_TYPE": "blackpearl_storage_policies#1.0.0",
        "s3_endpoint": "http://blackpearl.example.org:8080",
        "bp_access_id_file": "/etc/blackpearl/access-id-file"
      },
      "DATA_TYPE": "storage_gateway#1.0.0"
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}

400 - Bad request

401 - Unauthorized

403 - Missing required role

409 - ResourceConflict

415 - UnsupportedMedia

422 - UnprocessableEntity

Details

Get a Storage Gateway

GET /storage_gateways/{storage_gateway_id}

Get a StorageGateway document by its ID.

The include query parameter controls what additional information is included in the Result document.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator, endpoint:activity_manager, endpoint:activity_monitor, collection:administrator:{collection_id}, collection:activity_manager:{collection_id}, collection:activity_monitor:{collection_id}, collection:access_manager:{collection_id} ]
CollectionACLAuthorizer: [ {collection_id} ]
StorageGatewayAuthorizer [ {storage_gateway_id} ]

Query Parameters

Parameter	Type	Description
include	string `private_policies`, `accounts`	List of document types to include in the response. If "private_policies" is in the list, then include private storage gateway policies in the attached storage_gateways document. This requires the caller to have an `administrator` role on the Endpoint. If "accounts" is in the list, then include the list of accounts the caller’s identity set allows access to.

Responses

200 - Get Storage Gateway result

Table 3. application/json
Name	Type	Description
code	string `success`
data	array
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "data": [
    {
      "id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
      "display_name": "Posix Storage Gateway",
      "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
      "high_assurance": true,
      "require_high_assurance": true,
      "authentication_timeout_mins": 30,
      "authentication_assurance_timeout": 30,
      "allowed_domains": [
        "example.com"
      ],
      "identity_mappings": [
        {
          "DATA_TYPE": "external_identity_mapping#1.0.0",
          "command": [
            "/opt/globus/bin/python",
            "/opt/globus/map-globus-identity-data"
          ]
        }
      ],
      "users_allow": [
        "user1"
      ],
      "users_deny": [
        "user2"
      ],
      "restrict_paths": {
        "DATA_TYPE": "path_restrictions#1.0.0",
        "read": [
          "/public"
        ],
        "read_write": [
          "/home",
          "/projects"
        ],
        "none": [
          "/private"
        ]
      },
      "process_user": "gcsweb",
      "load_dsi_module": "google_drive",
      "policies": {
        "DATA_TYPE": "blackpearl_storage_policies#1.0.0",
        "s3_endpoint": "http://blackpearl.example.org:8080",
        "bp_access_id_file": "/etc/blackpearl/access-id-file"
      },
      "DATA_TYPE": "storage_gateway#1.0.0"
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}

401 - Unauthorized

403 - Permission Denied

404 - Not Found

Delete Storage Gateway

DELETE /storage_gateways/{storage_gateway_id}

Delete a StorageGateway by its ID.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Responses

200 - Delete Storage Gateway result

Table 4. application/json
Name	Type	Description
code	string `success`
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
data	array (object)
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string"
}

401 - Unauthorized

403 - Permission Denied

404 - Not Found

409 - Conflict

Update a Storage Gateway

PATCH /storage_gateways/{storage_gateway_id}

Update a Storage Gateway, change only the properties included in the input document. It returns a document containing the Storage Gateway after the changes have been applied. Items explicitly set to null in the input are removed from the Storage Gateway document.

The high_assurance property cannot be changed.

This operation may return a Conflict error if any collections exist which would be not be consistent with the change in Storage Gateway policies.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Request body

application/json

Name	Type	Description
body	StorageGateway One of { StorageGateway 1.0.0 , StorageGateway 1.1.0 }	A storage gateway provides the access policies for the endpoint’s connected storage systems. It is a named interface by which authorized users can create and manage collections on the connected storage system. A single storage system may be associated with multiple storage gateways, each with its own policies. Storage gateway policies describe what type connector the storage gateway uses, the paths it allows access to, the login requirements are for the storage gateway, and the algorithm to map Globus identities to the user namespace of the storage gateway (e.g. local accounts).

Example

{
  "id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
  "display_name": "Posix Storage Gateway",
  "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
  "high_assurance": true,
  "require_high_assurance": true,
  "authentication_timeout_mins": 30,
  "authentication_assurance_timeout": 30,
  "allowed_domains": [
    "example.com"
  ],
  "identity_mappings": [
    {
      "DATA_TYPE": "external_identity_mapping#1.0.0",
      "command": [
        "/opt/globus/bin/python",
        "/opt/globus/map-globus-identity-data"
      ]
    }
  ],
  "users_allow": [
    "user1"
  ],
  "users_deny": [
    "user2"
  ],
  "restrict_paths": {
    "DATA_TYPE": "path_restrictions#1.0.0",
    "read": [
      "/public"
    ],
    "read_write": [
      "/home",
      "/projects"
    ],
    "none": [
      "/private"
    ]
  },
  "process_user": "gcsweb",
  "load_dsi_module": "google_drive",
  "policies": {
    "DATA_TYPE": "blackpearl_storage_policies#1.0.0",
    "s3_endpoint": "http://blackpearl.example.org:8080",
    "bp_access_id_file": "/etc/blackpearl/access-id-file"
  },
  "DATA_TYPE": "storage_gateway#1.0.0"
}

Responses

200 - Update Storage Gateway result

Table 5. application/json
Name	Type	Description
code	string `success`
data	array ( StorageGateway )
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "data": [
    {
      "id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
      "display_name": "Posix Storage Gateway",
      "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
      "high_assurance": true,
      "require_high_assurance": true,
      "authentication_timeout_mins": 30,
      "authentication_assurance_timeout": 30,
      "allowed_domains": [
        "example.com"
      ],
      "identity_mappings": [
        {
          "DATA_TYPE": "external_identity_mapping#1.0.0",
          "command": [
            "/opt/globus/bin/python",
            "/opt/globus/map-globus-identity-data"
          ]
        }
      ],
      "users_allow": [
        "user1"
      ],
      "users_deny": [
        "user2"
      ],
      "restrict_paths": {
        "DATA_TYPE": "path_restrictions#1.0.0",
        "read": [
          "/public"
        ],
        "read_write": [
          "/home",
          "/projects"
        ],
        "none": [
          "/private"
        ]
      },
      "process_user": "gcsweb",
      "load_dsi_module": "google_drive",
      "policies": {
        "DATA_TYPE": "blackpearl_storage_policies#1.0.0",
        "s3_endpoint": "http://blackpearl.example.org:8080",
        "bp_access_id_file": "/etc/blackpearl/access-id-file"
      },
      "DATA_TYPE": "storage_gateway#1.0.0"
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}

400 - Bad request

401 - Unauthorized

403 - Missing required role

404 - Not Found

415 - UnsupportedMedia

422 - UnprocessableEntity

Update a Storage Gateway

PUT /storage_gateways/{storage_gateway_id}

Update a Storage Gateway, completely replacing its definition with the new document. It returns a document containing the Storage Gateway after the update has been applied.

This operation may return a Conflict error if any collections exist which would be not be consistent with the change in Storage Gateway policies.

The high_assurance property cannot be changed.

Authorization

RoleAuthorizer: [ endpoint:owner, endpoint:administrator ]

Request body

application/json

Name	Type	Description
body	StorageGateway One of { StorageGateway 1.0.0 , StorageGateway 1.1.0 }	A storage gateway provides the access policies for the endpoint’s connected storage systems. It is a named interface by which authorized users can create and manage collections on the connected storage system. A single storage system may be associated with multiple storage gateways, each with its own policies. Storage gateway policies describe what type connector the storage gateway uses, the paths it allows access to, the login requirements are for the storage gateway, and the algorithm to map Globus identities to the user namespace of the storage gateway (e.g. local accounts).

Example

{
  "id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
  "display_name": "Posix Storage Gateway",
  "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
  "high_assurance": true,
  "require_high_assurance": true,
  "authentication_timeout_mins": 30,
  "authentication_assurance_timeout": 30,
  "allowed_domains": [
    "example.com"
  ],
  "identity_mappings": [
    {
      "DATA_TYPE": "external_identity_mapping#1.0.0",
      "command": [
        "/opt/globus/bin/python",
        "/opt/globus/map-globus-identity-data"
      ]
    }
  ],
  "users_allow": [
    "user1"
  ],
  "users_deny": [
    "user2"
  ],
  "restrict_paths": {
    "DATA_TYPE": "path_restrictions#1.0.0",
    "read": [
      "/public"
    ],
    "read_write": [
      "/home",
      "/projects"
    ],
    "none": [
      "/private"
    ]
  },
  "process_user": "gcsweb",
  "load_dsi_module": "google_drive",
  "policies": {
    "DATA_TYPE": "blackpearl_storage_policies#1.0.0",
    "s3_endpoint": "http://blackpearl.example.org:8080",
    "bp_access_id_file": "/etc/blackpearl/access-id-file"
  },
  "DATA_TYPE": "storage_gateway#1.0.0"
}

Responses

200 - Update Storage Gateway result

Table 6. application/json
Name	Type	Description
code	string `success`
data	array ( StorageGateway )
DATA_TYPE	string `result#1.0.0`	Type of this document.
http_response_code	integer	Numeric HTTP response code
detail		Machine readable response details
message	string	Message describing this result.
has_next_page	boolean	Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation.
marker	string	Opaque marker that may be passed to this API call to fetch the next page of results if the returned document has `has_next_page` set to true.

{
  "code": "success",
  "data": [
    {
      "id": "fc1f3ba0-1fa4-42b2-8bb3-53983774fa5f",
      "display_name": "Posix Storage Gateway",
      "connector_id": "145812c8-decc-41f1-83cf-bb2a85a2a70b",
      "high_assurance": true,
      "require_high_assurance": true,
      "authentication_timeout_mins": 30,
      "authentication_assurance_timeout": 30,
      "allowed_domains": [
        "example.com"
      ],
      "identity_mappings": [
        {
          "DATA_TYPE": "external_identity_mapping#1.0.0",
          "command": [
            "/opt/globus/bin/python",
            "/opt/globus/map-globus-identity-data"
          ]
        }
      ],
      "users_allow": [
        "user1"
      ],
      "users_deny": [
        "user2"
      ],
      "restrict_paths": {
        "DATA_TYPE": "path_restrictions#1.0.0",
        "read": [
          "/public"
        ],
        "read_write": [
          "/home",
          "/projects"
        ],
        "none": [
          "/private"
        ]
      },
      "process_user": "gcsweb",
      "load_dsi_module": "google_drive",
      "policies": {
        "DATA_TYPE": "blackpearl_storage_policies#1.0.0",
        "s3_endpoint": "http://blackpearl.example.org:8080",
        "bp_access_id_file": "/etc/blackpearl/access-id-file"
      },
      "DATA_TYPE": "storage_gateway#1.0.0"
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "http_response_code": 200,
  "detail": null,
  "message": "Operation successful",
  "has_next_page": false,
  "marker": "string"
}