# Drives

## Drive API Method Specifications

### API method: `/drive/new`

#### Specification

This API creates a new drive from the specified external storage service. On success, the requesting user has permissions to perform tasks associated with the external storage.

#### Inputs

* `name` **string** (required) Name of the drive.
* `cloud` **string** (required) Drive cloud provider.
  * Must be one of `"azure"` or `"aws"`.
* `credentials` **mapping** (required) Credentials associated with the drive.
  * **key** — the credential field.
  * **value** **string** — the credential value.

#### Outputs

* `id` **string** ID of the created drive.

#### Errors

* Unauthorized
  * Must supply authentication token
* InvalidInput
  * The input is not a hash
  * `name` is not a nonempty string
  * `cloud` is not a string
  * `credentials` is not hash
  * `credentials` cannot access the given cloud environment

### API method: `/drive-xxxx/disable`

#### Specification

This API disables a drive. The requesting user must have permissions to use the drive.

#### Outputs

* `id` **string** ID of the disabled drive.

#### Errors

* Unauthorized
  * Must supply authentication token
* ResourceNotFound
  * The entity drive-xxxx could not be found

### API method: `/drive-xxxx/update`

#### Specification

Updates information about a drive. The requesting user must have permissions to use the drive.

#### Inputs

* `name` **string** (optional) New user-specified name of the drive.
* `credentials` **mapping** (optional) New credentials associated with the drive.
  * **key** — the credential field.
  * **value** **string** — the credential value.

#### Outputs

* `id` **string** ID of the updated drive.

#### Errors

* Unauthorized
  * Must supply authentication token
* InvalidInput
  * The input is not a hash
  * `name` (if provided) is not a nonempty string
  * `credentials` (if provided) is not hash
  * `credentials` (if provided) cannot access given cloud environment
* ResourceNotFound
  * The entity drive-xxxx could not be found

### API method: `/drive-xxxx/describe`

#### Specification

* Describes a drive.

#### Inputs

* `fields` **mapping** (optional) Include or exclude fields from the output.
  * **key** — the desired output field. See "Outputs" below for valid values.
  * **value** **boolean** — whether to include the field.

#### Outputs

* `id` **string** ID of the drive.
* `name` **string** Name of the drive.
* `cloud` **string** Cloud provider of the drive.
* `created` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which this object was created.
* `modified` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which this object was last modified.

#### Errors

* Unauthorized
  * Must supply authentication token
* InvalidInput
  * The input is not a hash
  * `fields` (if provided) is not hash
  * `name` (if provided) is not boolean
  * `cloud` (if provided) is not boolean
  * `id` (if provided) is not boolean
  * `created` (if provided) is not boolean
  * modified (if provided) is not boolean
* ResourceNotFound
  * The entity drive-xxxx could not be found