General notes
Each resource can be accessed or modified using specially formed URLs and the standard HTTP methods:
- GET to read
- POST to create
- PUT to update
- DELETE to remove
We require that all requests are done over SSL. The API supports JSON formats. Rucio uses OAuth
to authenticate all API requests. The method is to get an authentication token, and use it for the rest of
the requests. Descriptions of the actions you may perform on each resource can be found below.
Date format
All dates returned are in UTC and are strings in the following format (RFC 1123, ex RFC 822):
Mon, 13 May 2013 10:23:03 UTC
In code format, which can be used in all programming languages that support strftime or strptime:
'%a, %d %b %Y %H:%M:%S UTC'
SSL only
We require that all requests(except for the ping) are done over SSL.
Response formats
The currently-available response format for all REST endpoints is the string-based format JavaScript Object Notation(JSON).
The server answer can be one of the following content-type in the http Header:
Content-type: application/json
Content-Type: application/x-json-stream
In the last case, it corresponds to JSON objects delimited by newlines(streaming JSON for large answer), e.g.:
{ "id": 1, "foo": "bar" }
{ "id": 2, "foo": "baz" }
...
Error handling
Errors are returned using standard HTTP error code syntax.
Any additional info is included in the header of the return call, JSON-formatted with the parameters:
ExceptionClass
ExceptionMessage
Where ExceptionClass refers to Rucio Exceptions.
Service
-
class rucio.web.rest.ping.Ping[source]
Bases: rucio.web.rest.common.RucioController
-
GET()[source]
-
GET /ping
Get server version information.
Example request:
GET /ping HTTP/1.1
Host: rucio-server.com
Accept: application/json
Example response:
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"version": "0.2.9"
}
Status Codes: |
- 200 – no error
- 500 – InternalError
|
- GET /PING: Discover server version information
- Command: rucio ping, method: ping
Rucio account
- POST /accounts/{account_name}: Create account
- Command: rucio-admin account add, method: add_account
- GET /accounts/{account_name}: Get account information
- PUT /accounts/{account_name}: Update account information
- GET /accounts/{account_name}/usage: Get account usage information
- GET /accounts/{account_name}/limits: Get limits
- PUT /accounts/{account_name}/limits: Set limits for a account and a value
- GET /accounts/{account_name}/rules: Get all rules of the account
- GET /accounts/whoami: Get information about account whose token is used
- GET /accounts/: List available accounts
- DELETE /accounts/{account_name}: Disable account name
RSE (Rucio Storage Element)
- POST /rses/(rse_name): Create a RSE
- Command: rucio-admin rse add
- Method: add_rse
- GET /rses/{rse_name}: Get RSE information
- GET /rses/: List available RSEs
- DELETE /rses/{rse_name}: Disable a RSE
- GET /rses/{rse_name}/usage: Get RSE usage information
- GET /rses/{rse_name}/usage/history: Get RSE usage information history
RSE attributes
- GET /rses/{rse_name}/attr/: List all keys of the RSE with their respective values
- GET /rses/{rse_name}/attr/{key}: Get the value of the RSE attribute/key
- POST /rses/{rse_name}/attr/{key}: Create an RSE key
- PUT /rses/{rse_name}/attr/{key}: Update the value of a key
- DELETE /rses/{rse_name}/attr/{key}: Remove a key from a RSE
Identity
- POST /accounts/{account_name}/identities/{userpass|x509|gss|proxy}/{identityString}: Grant a {userpass|x509|gss|proxy} identity access to an account
- GET /accounts/{account_name}/identities: List all identities on an account
- GET /identities/{userpass|x509|gss|proxy}/{identityString}/accounts/: List all account memberships of an identity
- DELETE /accounts/{account_name}/identities/{userpass|x509|gss|proxy}/{identityString}: Revoke a {userpass|x509|gss|proxy} identity’s access to an account
Scope
- POST /accounts/{account_name}/scopes/{scope_name}: Create a scope
- GET /accounts/{account_name}/scopes/: List available scopes for an account
- GET /scopes/: List/query all scopes with filter parameter lists
- DELETE /accounts/{account_name}/scopes/{scope_name}: Delete a scope from an account
Data identifiers
- GET /dids/: Search data identifiers over all scopes with filter parameters
- POST /dids/{scope_name}/{did}: Create a new data identifier
- GET /dids/{scope_name}/: List all data identifiers in a scope
- DELETE /dids/{scope_name}/{did}: Obsolete a data identifier
- GET /dids/{scope_name}/{did}/rses/: List replicas for a data identifier
- GET /dids/{scope_name}/{did}/: List content of data identifier
- PUT /dids/{scope_name}/{did}/status: Update data identifier status
- GET /dids/{scope_name}/{did}/status: Get data identifier status
- GET /dids/{scope_name}/{did}/rules: List all rules of this did
- GET /dids/{scope_name}/{did}/meta/: List all keys of the data identifier with their respective values
- GET /dids/{scope_name}/{did}/meta/{key}: Retrieve the selected key value pair for the given data identifier
- PUT /dids/{scope_name}/{did}/meta/{key}: Set the value of the key to NULL ?
- DELETE /dids/{scope_name}/{did}/meta/{key}: Remove a key from a data identifier
- PUT /dids/{scope_name}/{did}/meta/{key}: Set the value of the key of a data identifier
- POST /dids/{scope_name}/{did_super}/{did_sub}: Add “sub” data identifier into “super” data identifier
Replication rule
- POST /rules/: Create a rule on a data identifier
- GET /rules/{rule_id}: Get all the rules associated to a data identifier
- DELETE /rules/{rule_id}: Delete a rule
Subscriptions
- POST /subscriptions/{account_name}/: Register a subscription
- DELETE /subscriptions/{subscription_id}: Delete a subscription
- GET /subscriptions/{subscription_id}: Get subscription info
- GET /subscriptions/: List all subscriptions
- GET /subscriptions/{subscription_id}/rules: Get all rules of this subscription