# 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

Copyright European Organization for Nuclear Research (CERN)

Licensed under the Apache License, Version 2.0 (the “License”); You may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Authors: - Vincent Garonne, <vincent.garonne@cern.ch>, 2012-2017 - Thomas Beermann, <thomas.beermann@cern.ch>, 2012 - Mario Lassnig, <mario.lassnig@cern.ch>, 2014

class `rucio.web.rest.ping.``Ping`

  Bases: `rucio.web.rest.common.RucioController`

  Ping class

  `GET`()
    `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 OK – no error 500 Internal Server Error – InternalError

- GET /PING: Discover server version information
  - Command: rucio ping, method: ping

## Authentication

- GET /auth/userpass: Retrieve an auth token with an username and password
- GET /auth/x509: Retrieve an auth token with a x509 certificate
- GET /auth/x509_proxy: Retrieve an auth token with a Globus proxy
- GET /auth/gss: Retrieve an auth token with a gss token
- GET /auth/validate: Retrieve an auth token with a gss token
- DELETE /auth/{token}: Revoke a token

## 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

## Metadata

- POST /meta/{key}: Create a new allowed key (value is NULL)
- GET /meta/: List all allowed keys with their default values
- POST /meta/{key}: Create a new allowed key with a default value
- DELETE /meta/{key}: Delete an allowed key
- DELETE /meta/{key}/{defaultvalue}: Delete the default value of a key (change the value to NULL)

## 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