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.