# REST API Examples Using Curl

Below are some examples of The Rucio REST API with Curl. We assume that there is a Rucio server running on the localhost on port 80/443.

## Service

### GET /PING

Discover server version information.

Responses

> - `200 OK`

Example Request

    $> curl -s  -X GET http://localhost/ping
    {"version": "0-37-g7213ca2-dev1350298880"}

## Authentication

### GET /auth/userpass

Requesting a X-Rucio-Auth-Token with curl via username and password.

Responses

> - `200 OK`
> - `401 Unauthorized`

Example Request

    $> curl -s -i --cacert /opt/rucio/etc/web/ca.crt  -X GET -H "X-Rucio-Account: root" -H "Rucio-Username: ddmlab" -H "Rucio-Password: secret" https://localhost/auth/userpass
    HTTP/1.1 200 OK
    Date: Mon, 15 Oct 2012 11:37:33 GMT
    Server: Apache/2.2.22 (Unix) mod_ssl/2.2.22 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.15 mod_fastcgi/2.4.2
    X-X-X-Rucio-Auth-Token: bad32ab79a1648128b5343b29580d96c
    Content-Length: 0
    Content-Type: application/octet-stream

### GET /auth/x509

Requesting a X-Rucio-Auth-Token with curl via a X509 certificate.

Responses

> - `200 OK`
> - `401 Unauthorized`

Example Request

    $> curl -s -i --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Account: root" -E /opt/rucio/etc/web/client.crt -X GET https://localhost/auth/x509
    HTTP/1.1 200 OK
    Date: Mon, 15 Oct 2012 11:37:33 GMT
    Server: Apache/2.2.22 (Unix) mod_ssl/2.2.22 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.15 mod_fastcgi/2.4.2
    X-X-X-X-X-Rucio-Auth-Token: 928c0a4747d346999cfaceac0b4a171d
    Content-Length: 0
    Content-Type: application/octet-stream

### GET /auth/gss

Requesting a X-Rucio-Auth-Token with curl via kerberos.

Responses

> - `200 OK`
> - `401 Unauthorized`

Example Request

### GET /auth/x509_proxy

Requesting a X-Rucio-Auth-Token with curl via a Globus proxy.

Responses

> - `200 OK`
> - `401 Unauthorized`

Example Request

    $> curl -s -i --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Account: vgaronne" --cert $X509_USER_PROXY --key $X509_USER_PROXY -X GET https://localhost/auth/x509_proxy
    HTTP/1.1 200 OK
    Date: Mon, 15 Oct 2012 10:58:37 GMT
    Server: Apache/2.2.22 (Unix) mod_ssl/2.2.22 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.15 mod_fastcgi/2.4.2
    X-X-X-Rucio-Auth-Token: 10520defe5314ef68677be7a479152ae
    Content-Length: 0
    Content-Type: application/octet-stream

### GET /auth/validate

Check the validity of a authentication token. Checking the validity of a token will extend its lifetime by one hour.

Responses

> - `200 OK`: the token is valid
> - `401 Unauthorized`: The token is not valid

Example Request

    $> curl -s -i --cacert /opt/rucio/etc/web/ca.crt  -H "X-X-X-Rucio-Auth-Token: $RUCIO_TOKEN" -X GET https://localhost/auth/validate
    HTTP/1.1 200 OK
    Date: Mon, 15 Oct 2012 11:37:33 GMT
    Server: Apache/2.2.22 (Unix) mod_ssl/2.2.22 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.15 mod_fastcgi/2.4.2
    Content-Length: 85
    Content-Type: application/octet-stream

    {'lifetime': datetime.datetime(2012, 10, 15, 11, 58, 35, 832646), 'account': u'root'}

### GET /auth/register_api_token

Responses

Example Request

Example Response

## Account

### POST /accounts/{accountName}

Create account.

Parameters

Name | Type | Description
--- | --- | ---
`accountType` | String | The type of the account (user, group, atlas)

Responses

> - `201 Created`: Account created
> - `409 Conflict`: Account already exists
> - `401 Unauthorized`

Example Request

    HTTP/1.1 201 Created

### GET /accounts/{accountName}

Get account information.

Responses

> - `200 OK`
> - `404 Not Found`

Example Request

    curl -s -i --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Auth-Token: $TOKEN" -X GET https://localhost/accounts/jdoe

Example Response

    HTTP/1.1 200 OK
    Date: Wed, 04 Jul 2012 13:37:04 GMT
    Server: Apache/2.2.21 (Unix) mod_fastcgi/2.4.2 mod_ssl/2.2.21 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.8
    Transfer-Encoding: chunked
    Content-Type: application/json

    {"status": "active", "account": "jdoe", "deleted": false, "created_at": "2012-07-04T13:37:04", "updated_at": "2012-07-04T13:37:04", "deleted_at": null, "type": "user"}

### PUT accounts/{accountName}

Update account information

Responses

> - `200 OK`
> - `404 Not Found`

Example Request

Example Response

    HTTP/1.1 201 Created
    Date: Wed, 04 Jul 2012 13:37:04 GMT
    Server: Apache/2.2.21 (Unix) mod_fastcgi/2.4.2 mod_ssl/2.2.21 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.8
    Transfer-Encoding: chunked
    Content-Type: application/octet-stream

    Created

### GET accounts/whoami

Get information about account whose token is used to sign the request.

Responses

> - `303 See Other`

Example Request

    curl -s -i -L --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Auth-Token: $TOKEN" -X GET https://localhost/accounts/whoami

Example Response

    HTTP/1.1 303 See Other
    Date: Wed, 04 Jul 2012 13:37:05 GMT
    Server: Apache/2.2.21 (Unix) mod_fastcgi/2.4.2 mod_ssl/2.2.21 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.8
    Location: https://localhost/account/root
    Content-Length: 0
    Content-Type: text/html

    HTTP/1.1 200 OK
    Date: Wed, 04 Jul 2012 13:37:05 GMT
    Server: Apache/2.2.21 (Unix) mod_fastcgi/2.4.2 mod_ssl/2.2.21 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.8
    Transfer-Encoding: chunked
    Content-Type: application/json

    {"status": "active", "account": "root", "deleted": false, "created_at": "2012-07-04T13:36:58", "updated_at": "2012-07-04T13:36:58", "deleted_at": null, "type": "user"}

### GET accounts/

List available accounts.

Responses

> - `200 OK`

Example Request

    curl -s -i --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Auth-Token: $TOKEN" -X GET https://localhost/accounts/

Example Response

    HTTP/1.1 200 OK
    Date: Wed, 04 Jul 2012 13:37:05 GMT
    Server: Apache/2.2.21 (Unix) mod_fastcgi/2.4.2 mod_ssl/2.2.21 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.8
    Transfer-Encoding: chunked
    Content-Type: application/json

    ["jdoe", "root"]

### DELETE accounts/{accountName}

Disable an account.

Responses

> - `200 OK`

Example Request

    curl -s -i --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Auth-Token: $TOKEN" -X DELETE https://localhost/accounts/jdoe

Example Response

    HTTP/1.1 200 OK
    Date: Wed, 04 Jul 2012 13:37:05 GMT
    Server: Apache/2.2.21 (Unix) mod_fastcgi/2.4.2 mod_ssl/2.2.21 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.8
    Content-Length: 0
    Content-Type: application/octet-stream

## Location

### POST locations/

Create a location

Parameters

Name | Type | Description
--- | --- | ---
`locationName` | String | The name of the location

Responses

> - `201 Created`: Location created
> - `409 Conflict`: Location already exists
> - `401 Unauthorized`

Example Request

    curl -s -i --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Auth-Token: $TOKEN" -d '{"location":"MOCK"}' -X POST https://localhost/locations/

Example Response

### GET locations/{locationName}

Get location information.

Responses

> - `200 OK`

Example Request

    curl -s -i --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Auth-Token: $TOKEN" -X GET https://localhost/locations/MOCK

Example Response

    HTTP/1.1 405 Method Not Allowed
    Date: Wed, 04 Jul 2012 13:37:05 GMT
    Server: Apache/2.2.21 (Unix) mod_fastcgi/2.4.2 mod_ssl/2.2.21 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.8
    Allow: POST
    Transfer-Encoding: chunked
    Content-Type: text/html
    X-Pad: avoid browser bug

    None

### GET locations/

List available locations.

Responses

> - `200 OK`

Example Request

    curl -s -i --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Auth-Token: $TOKEN" -X GET https://localhost/locations/

Example Response

    HTTP/1.1 200 OK
    Date: Wed, 04 Jul 2012 13:37:05 GMT
    Server: Apache/2.2.21 (Unix) mod_fastcgi/2.4.2 mod_ssl/2.2.21 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.8
    Transfer-Encoding: chunked
    Content-Type: application/json

    []

### DELETE locations/{locationName}

Disable a location.

Responses

> - `200 OK`

Example Request

    curl -s -i --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Auth-Token: $TOKEN" -X DELETE https://localhost/locations/MOCK

Example Response

    HTTP/1.1 405 Method Not Allowed
    Date: Wed, 04 Jul 2012 13:37:05 GMT
    Server: Apache/2.2.21 (Unix) mod_fastcgi/2.4.2 mod_ssl/2.2.21 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.8
    Allow: POST
    Transfer-Encoding: chunked
    Content-Type: text/html
    X-Pad: avoid browser bug

    None

## Rucio Storage Element

### POST /locations/{locationName}/rses/

Tag a location with a RSE.

Parameters

Name | Type | Description
--- | --- | ---
`rseName` | String | RSE name
`description` (optional) | String | Description of the RSE

Responses

> - `201 Created`: Location-RSE created
> - `409 Conflict`: Location-RSE already exists
> - `401 Unauthorized`

Example Request

    curl -s -i --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Auth-Token: $TOKEN" -d '{"rseName":"CLOUD_MOCK", "description":"cloud"}' -X POST https://localhost/locations/MOCK/rses/

Example Response

### GET locations/{locationName}/rses/

List all RSEs associated to a location.

Responses

> - `200 OK`

Example Request

Example Response

### GET rses/

List all RSEs.

Parameters

Name | Type | Description
--- | --- | ---
`description` (optional) | String | Description of the RSE

Responses

> - `200 OK`
> - `404 Not Found`

Example Request

Example Response

### DELETE locations/{locationName}/rses/{rseName}

Remove a location from a RSE.

Responses

> - `200 OK`

Example Request

Example Response

## Identity

### POST accounts/{accountName}/identities/

Grant an x509|gss|userpass identity access to an account.

Parameters

Name | Type | Description
--- | --- | ---
`type` | String | x509|gss|userpass
`identity` | String | DN|username|gss user

Responses

> - `201 Created`: Account-identity created
> - `409 Conflict`: Account-identity already exists
> - `401 Unauthorized`

Example Request

Example Response

### GET accounts/{accountName}/identities/

List all identities on an account.

Parameters

Name | Type | Description
--- | --- | ---
``type` ` (optional) | String | x509|gss|userpass

Responses

> - `200 OK`

Example Request

Example Response

### GET identities/{x509|gss|userpass}/{id}/accounts/

List all accounts an identity is member of.

Responses

> - `200 OK`

Example Request

Example Response

### DELETE accounts/{accountName}/identities/{x509|gss|userpass}/{id}

Revoke an x509|gss|userpass identity’s access to an account.

Responses

> - `200 OK`

Example Request

Example Response

## Scope

### POST accounts/{accountName}/scopes/

Create a scope within an account.

Parameters

Name | Type | Description
--- | --- | ---
`scopeName` | String | Scope name

Responses

> - `201 Created`: Account-scope created
> - `409 Conflict`: Account-scope already exists
> - `401 Unauthorized`

Example Request

Example Response

### GET accounts/{accountName}/scopes/

Get the scopes for an account.

Responses

> - `200 OK`

Example Request

Example Response

### GET scopes/

List all scopes.

Responses

> - `200 OK`

Example Request

    curl -s -i --cacert /opt/rucio/etc/web/ca.crt -H "X-Rucio-Auth-Token: $TOKEN" -X GET https://localhost/scope/ddmlab/

Example Response

    HTTP/1.1 500 Internal Server Error
    Date: Wed, 04 Jul 2012 13:37:06 GMT
    Server: Apache/2.2.21 (Unix) mod_fastcgi/2.4.2 mod_ssl/2.2.21 OpenSSL/0.9.8r DAV/2 mod_wsgi/3.3 Python/2.7.3 PHP/5.3.8
    Connection: close
    Transfer-Encoding: chunked
    Content-Type: text/html

    AccountNotFound: Account does not exist.
    Details: Account ID 'ddmlab/' does not exist
    {}

### DELETE accounts/{accountName}/scopes/{scopeName}

Delete a scope from an account.

Responses

> - `200 OK`

Example Request

Example Response

## Dataset

### POST datasets/{scopeName}/

Register a dataset.

Parameters

Name | Type | Description
--- | --- | ---
`datasetName` | String | dataset name
`...` | … | …

Responses

> - `201 Created`: Dataset created
> - `409 Conflict`: Dataset already exists
> - `401 Unauthorized`

Example Request

Example Response

### GET datasets/{scopeName}/{datasetName}/

List dataset content.

Responses

> - `200 OK`

Example Request

Example Response

### GET datasets/{scopeName}/{datasetName}

List dataset meta-data.

Responses

> - `200 OK`

Example Request

Example Response

### PUT datasets/{datasetName}

Update dataset meta-data.

### POST datasets/{scopeName}/{datasetName}/

Add file(s) to a dataset.

### GET datasets/{scopeName}/{datasetName}/{fileName}

Get file meta-data.

### GET datasets/

## File

### POST /locations/{locationName}/files/

Register a file.

Parameters

Name | Type | Description
--- | --- | ---
`fileName` | String | file name
`...` | … | …

Responses

> - `201 Created`: File created
> - `409 Conflict`: File already exists
> - `401 Unauthorized`

Example Request

Example Response

### GET /files/{scopeName}/locations/

List file replicas.

### PUT /files/{scopeName}/{fileName}/

Update file meta-data.

### GET /files/{scopeName}/{fileName}

### GET files/

Search files.