DID Rest API¶

Overview

Resource	Operation	Description
	POST /dids/bulkmeta
AssociatedRules	GET /dids/(scope)/(name)/associated_rules	List associated rules of DID.
Attachement	GET /dids/(scope)/(name)/dids	Get DID contents.
AttachementHistory	GET /dids/(scope)/(name)/dids/history	List the content history of a DID.
Attachements	POST /dids/attachments	Attach DIDs to DIDs.
Attachment	POST /dids/(scope)/(name)/dids	Append DID to DID.
BulkDID	POST /dids/	Bulk add DIDs.
DIDs	POST /dids/(scope)/(name)	Create a new DID.
	GET /dids/(scope)/(name)	Retrieve a single DID.
	PUT /dids/(scope)/(name)/status	Update DID status.
	DELETE /dids/(scope)/(name)/dids	Detach DID from DID.
Files	GET /dids/(scope)/(name)/files	List replicas of DID.
GUIDLookup	GET /dids/(guid)/guid	List file by GUID.
Meta	POST /dids/(scope)/(name)/meta/(key)	Add DID metadata.
	GET /dids/(scope)/(name)/meta	List DID metadata.
NewDIDs	GET /dids/new	List recent DIDs.
Parents	GET /dids/(scope)/(name)/parents	List parents of DID.
Resurrect	POST /dids/resurrect	Resurrect DID.
Rules	GET /dids/(scope)/(name)/rules	List rules of DID.
Sample	POST /dids/(input_scope)/(input_name)/(output_scope)/(output_name)/(nbfiles)/sample	Create a sample DID.
Scopes	GET /dids/(scope)/	List all dids for scope
Search	GET /dids/(scope)/dids/search_extended	Search DIDs in a scope with given metadata.
	GET /dids/(scope)/dids/search

Details

POST /dids/attachments¶: Attach DIDs to DIDs

POST /dids/resurrect¶

Resurrect DIDs.

HTTP Success:: 201 Created
HTTP Error:: 401 Unauthorized 404 Not Found 409 Conflict 500 Internal Error

POST /dids/bulkmeta¶

List all meta of a list of data identifiers. HTTP Success:

200 OK

HTTP Error:: 400 Bad Request 401 Unauthorized 404 DataIdentifierNotFound 500 InternalError

Returns: A list of dictionaries containing all meta.

GET /dids/new¶

Returns list of recent identifiers.

Response Headers

Content-Type – application/x-json-stream

Query Parameters

type – the DID type.

Status Codes

200 OK – DIDs found
401 Unauthorized – Invalid Auth Token
406 Not Acceptable – Not Acceptable
500 Internal Server Error – Database Exception

Returns

List recently created DIDs.

POST /dids/¶

Add new DIDs in bulk.

POST /dids/ HTTP/1.1
Host: rucio.cern.ch

[
  {"scope": "scope1", "type": "CONTAINER", "name": "container1",
   "account": "jdoe", "length": 1},
  {"scope": "scope1", "type": "DATASET", "name": "dataset1",
   "account": "jdoe", "length": 3}
]

Example response:

HTTP/1.1 201 Created
Vary: Accept

Request Headers

Accept – application/json

Request JSON Object

scope (string) – the new DID scope
name (string) – the new DID name
type (string) – the new DID type
account (string) – the owner account of the new DID
statuses (string) – monotonic

Status Codes

201 Created – new DIDs created
401 Unauthorized – Invalid Auth Token
406 Not Acceptable – Not Acceptable
409 Conflict – DID already exists
500 Internal Server Error – Database Exception

GET /dids/(scope)/dids/search_extended¶

List all data identifiers in a scope which match a given metadata. Extended Version to included meteadata from various plugins.

Example request:

GET /dids/scope1/dids/search_extended?type=collection&long=True&length.lt=10 HTTP/1.1
Host: rucio.cern.ch

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/x-json-stream

{"scope": "scope1", "did_type": "CONTAINER", "name": "container1",
 "bytes": 1234, "length": 1}
{"scope": "scope1", "did_type": "DATASET", "name": "dataset1",
 "bytes": 234, "length": 3}

Query Parameters

type – specify a DID type to search for
limit – The maximum number of DIDs returned.
long – set to True for long output, otherwise only name
recursive – set to True to recursively list DIDs content
created_before – Date string in RFC-1123 format where the creation date was earlier
created_after – Date string in RFC-1123 format where the creation date was later
length – Exact number of attached DIDs
length.gt – Number of attached DIDs greater than
length.lt – Number of attached DIDs less than
length.gte – Number of attached DIDs greater than or equal to
length.lte – Number of attached DIDs less than or equal to
name – Name or pattern of a DID name

Response Headers

Content-Type – application/x-json-stream

Status Codes

200 OK – DIDs found
401 Unauthorized – Invalid Auth Token
404 Not Found – Invalid key in filters
406 Not Acceptable – Not Acceptable
409 Conflict – Wrong DID type

Returns

Line separated name of DIDs or dictionaries of DIDs for long option

GET /dids/(scope)/dids/search¶

List all data identifiers in a scope which match a given metadata.

Example request:

GET /dids/scope1/dids/search?type=collection&long=True&length.lt=10 HTTP/1.1
Host: rucio.cern.ch

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/x-json-stream

{"scope": "scope1", "did_type": "CONTAINER", "name": "container1",
 "bytes": 1234, "length": 1}
{"scope": "scope1", "did_type": "DATASET", "name": "dataset1",
 "bytes": 234, "length": 3}

Query Parameters

type – specify a DID type to search for
limit – The maximum number of DIDs returned.
long – set to True for long output, otherwise only name
recursive – set to True to recursively list DIDs content
created_before – Date string in RFC-1123 format where the creation date was earlier
created_after – Date string in RFC-1123 format where the creation date was later
length – Exact number of attached DIDs
length.gt – Number of attached DIDs greater than
length.lt – Number of attached DIDs less than
length.gte – Number of attached DIDs greater than or equal to
length.lte – Number of attached DIDs less than or equal to
name – Name or pattern of a DID name

Response Headers

Content-Type – application/x-json-stream

Status Codes

200 OK – DIDs found
401 Unauthorized – Invalid Auth Token
404 Not Found – Invalid key in filters
406 Not Acceptable – Not Acceptable
409 Conflict – Wrong DID type

Returns

Line separated name of DIDs or dictionaries of DIDs for long option

GET /dids/(scope)/(name)/dids/history¶

Returns the contents history of a data identifier.

Response Headers

Content-Type – application/x-json-stream

Parameters

scope – The scope of the data identifier.
name – The name of the data identifier.

Status Codes

200 OK – DID found
401 Unauthorized – Invalid Auth Token
404 Not Found – DID not found
406 Not Acceptable – Not Acceptable
500 Internal Server Error – Database Exception

Returns

Stream of dictionarys with DIDs

GET /dids/(guid)/guid¶

Return the file associated to a GUID.

Response Headers

Content-Type – application/x-json-stream

Parameters

guid – the GUID to query by.

Status Codes

200 OK – DID found
401 Unauthorized – Invalid Auth Token
404 Not Found – DID not found
406 Not Acceptable – Not Acceptable
500 Internal Server Error – Database Exception

Returns

List of files for given GUID

GET /dids/(scope)/(name)/associated_rules¶

Return all associated rules of a file.

Response Headers

Content-Type – application/x-json-stream

Parameters

scope – The scope of the data identifier.
name – The name of the data identifier.

Status Codes

200 OK – DID found
401 Unauthorized – Invalid Auth Token
404 Not Found – DID not found
406 Not Acceptable – Not Acceptable
500 Internal Server Error – Database Exception

Returns

List of associated rules.

GET /dids/(scope)/(name)/parents¶

List all parents of a data identifier.

Response Headers

Content-Type – application/x-json-stream

Parameters

scope – The scope of the data identifier.
name – The name of the data identifier.

Status Codes

200 OK – DID found
401 Unauthorized – Invalid Auth Token
404 Not Found – DID not found
406 Not Acceptable – Not Acceptable.
500 Internal Server Error – Database Exception

Returns

A list of dictionary containing all dataset information.

POST /dids/(scope)/(name)¶

Create a new data identifier.

POST /dids/scope1/container1 HTTP/1.1
Host: rucio.cern.ch

{"type": "CONTAINER", "lifetime": 86400},

Example response:

HTTP/1.1 201 Created
Vary: Accept

Request Headers

Accept – application/json

Parameters

scope – data identifier scope.
name – data identifier name.

Request JSON Object

type (string) – the new DID type
statuses (dict) – Dictionary with statuses, e.g. {‘monotonic’:True}
meta (dict) – Dictionary with metadata, e.g. {‘length’:1234}
rules (dict) – Replication rules associated with the did. e.g., [{‘copies’: 2, ‘rse_expression’: ‘TIERS1’}, ]
lifetime (int) – DID’s liftime in seconds.
dids (list) – The content.
rse (string) – The RSE name when registering replicas.

Status Codes

201 Created – new DIDs created
401 Unauthorized – Invalid Auth Token
409 Conflict – DID already exists
500 Internal Server Error – Database Exception

GET /dids/(scope)/(name)¶

Retrieve a single data identifier.

Example request:

GET /dids/scope1/dataset1?dynamic HTTP/1.1
Host: rucio.cern.ch

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{"scope": "scope1", "did_type": "DATASET", "name": "dataset1",
 "bytes": 234, "length": 3, "account": "jdoe", "open": True,
 "monotonic": False, "expired_at": null}

Query Parameters

dynamic – Flag to dynamically calculate size for open DIDs

Response Headers

Content-Type – application/json

Status Codes

200 OK – DID found
401 Unauthorized – Invalid Auth Token
404 Not Found – Scope not found
406 Not Acceptable – Not Acceptable.

Returns

Dictionary with DID metadata

PUT /dids/(scope)/(name)/status¶

Update data identifier status.

PUT /dids/scope1/container1 HTTP/1.1
Host: rucio.cern.ch

{"open": False},

Example response:

HTTP/1.1 200 OK
Vary: Accept

Parameters

scope – data identifier scope.
name – data identifier name.

Request JSON Object

open (bool) – open or close did

Status Codes

200 OK – DIDs successfully updated
401 Unauthorized – Invalid Auth Token
404 Not Found – DID not found
409 Conflict – Wrong status
500 Internal Server Error – Database Exception

GET /dids/(scope)/(name)/files¶

List all replicas of a data identifier.

Response Headers

Content-Type – application/x-json-stream

Parameters

scope – The scope of the data identifier.
name – The name of the data identifier.

Query Parameters

long – Flag to trigger long output

Status Codes

200 OK – DID found
401 Unauthorized – Invalid Auth Token
404 Not Found – DID not found
406 Not Acceptable – Not Acceptable
500 Internal Server Error – Database Exception

Returns

A dictionary containing all replicas information.

GET /dids/(scope)/(name)/rules¶

Return all rules of a given DID.

Response Headers

Content-Type – application/x-json-stream

Parameters

scope – The scope of the data identifier.
name – The name of the data identifier.

Status Codes

200 OK – DID found
401 Unauthorized – Invalid Auth Token
404 Not Found – DID not found
406 Not Acceptable – Not Acceptable
500 Internal Server Error – Database Exception

Returns

List of replication rules.

POST /dids/(scope)/(name)/meta/(key)¶

Add metadata to a data identifier.

HTTP Success:: 201 Created
HTTP Error:: 400 Bad Request 401 Unauthorized 404 Not Found 409 Conflict 500 Internal Error

Parameters

scope – The scope name.
name – The data identifier name.
key – the key.

GET /dids/(scope)/(name)/meta¶

List all meta of a data identifier.

Response Headers

Content-Type – application/json

Parameters

scope – The scope of the data identifier.
name – The name of the data identifier.

Status Codes

200 OK – DID found
401 Unauthorized – Invalid Auth Token
404 Not Found – DID not found
406 Not Acceptable – Not Acceptable
500 Internal Server Error – Database Exception

Returns

A dictionary containing all meta.

DELETE /dids/(scope)/(name)/dids¶

Detach data identifiers from data identifiers.

Parameters

scope – Scope of the DID to detach from.
name – Name of the DID to detach from.

Request JSON Object

data (dicts) – Must contain key ‘dids’ with list of dids to detach.

Status Codes

200 OK – DIDs successfully detached
401 Unauthorized – Invalid Auth Token
404 Not Found – DID not found
500 Internal Server Error – Database Exception

POST /dids/(scope)/(name)/dids¶

Append data identifiers to data identifiers.

Example request:

POST /dids/scope1/datasets1/dids HTTP/1.1
Host: rucio.cern.ch

[{"scope": "scope1", "name": "file1"},
 {"scope": "scope1", "name": "file2"},
 {"scope": "scope1", "name": "file3"}]

Example response:

HTTP/1.1 201 Created
Vary: Accept

Parameters

scope – The scope of the DID to attach to.
name – The name of the DID to attach to.

Request JSON Object

attachments (list) – List of dicts of DIDs to attach.

Status Codes

201 Created – DIDs successfully attached
401 Unauthorized – Invalid Auth Token
404 Not Found – DID not found
409 Conflict – DIDs already attached
500 Internal Server Error – Database Exception

GET /dids/(scope)/(name)/dids¶

Returns the contents of a data identifier.

Example request:

GET /dids/scope1/dataset1?dynamic HTTP/1.1
Host: rucio.cern.ch

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{"scope": "scope1", "did_type": "DATASET", "name": "dataset1",
 "bytes": 234, "length": 3, "account": "jdoe", "open": True,
 "monotonic": False, "expired_at": null}

Query Parameters

dynamic – Flag to dynamically calculate size for open DIDs

Response Headers

Content-Type – application/x-json-stream

Status Codes

200 OK – DID found
401 Unauthorized – Invalid Auth Token
404 Not Found – Scope not found
406 Not Acceptable – Not Acceptable

Returns

Dictionary with DID metadata

POST /dids/(input_scope)/(input_name)/(output_scope)/(output_name)/(nbfiles)/sample¶

Return the file associated to a GUID.

HTTP Success:: 201 Created
HTTP Error:: 401 Unauthorized 404 Not Found 409 Conflict 500 Internal Error

Parameters

input_scope – The scope of the input DID.
input_name – The name of the input DID.
output_scope – The scope of the output dataset.
output_name – The name of the output dataset.
nbfiles – The number of files to register in the output dataset.

GET /dids/(scope)/¶

Return all data identifiers in the given scope.

Example request:

GET /dids/scope1/?name=container1&recursive HTTP/1.1
Host: rucio.cern.ch

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/x-json-stream

{"scope": "scope1", "type": "CONTAINER", "name": "container1",
 "parent": null, "level": 0}
{"scope": "scope1", "type": "DATASET", "name": "dataset1", "parent":
 {"scope": "scope1", "name": "container1"}, "level": 1}
{"scope": "scope1", "type": "FILE", "name": "file1", "parent":
 {"scope": "scope1", "name": "dataset1"}, "level": 2}

Query Parameters

name – specify a DID name
recursive – flag to do a recursive search

Response Headers

Content-Type – application/x-json-stream

Status Codes

200 OK – DIDs found
401 Unauthorized – Invalid Auth Token
404 Not Found – no DIDs found in scope
406 Not Acceptable – Not Acceptable

Returns

Line separated dictionaries of DIDs