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 valid401 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'}
Account¶
POST /accounts/{accountName}¶
Create account.
Parameters
Name | Type | Description |
---|---|---|
accountType |
String | The type of the account (user, group, atlas) |
Responses
201 Created
: Account created409 Conflict
: Account already exists401 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 created409 Conflict
: Location already exists401 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 created409 Conflict
: Location-RSE already exists401 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 created409 Conflict
: Account-identity already exists401 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 created409 Conflict
: Account-scope already exists401 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 created409 Conflict
: Dataset already exists401 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 created409 Conflict
: File already exists401 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.