DID Rest API

Overview

Resource Operation Description
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 PUT /dids/(scope)/(name)/status Update DID status.
  POST /dids/(scope)/(name) Create a new DID.
  GET /dids/(scope)/(name) Retrieve a single DID.
  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 Search DIDs in a scope with given metadata.

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
GET /dids/new

Returns list of recent identifiers.

Response Headers:
 
Query Parameters:
 
  • type – the DID type.
Status Codes:
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:
 
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:

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

Example request:

GET /dids/scope1/dids/search?type=collection1&long=True 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
  • long – set to True for long output, otherwise only name
  • recursive – recursively list DIDs content
Response Headers:
 
Status Codes:
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:
 
Parameters:
  • scope – The scope of the data identifier.
  • name – The name of the data identifier.
Status Codes:
Returns:

Stream of dictionarys with DIDs

GET /dids/(guid)/guid

Return the file associated to a GUID.

Response Headers:
 
Parameters:
  • guid – the GUID to query by.
Status Codes:
Returns:

List of files for given GUID

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

Return all associated rules of a file.

Response Headers:
 
Parameters:
  • scope – The scope of the data identifier.
  • name – The name of the data identifier.
Status Codes:
Returns:

List of associated rules.

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

List all parents of a data identifier.

Response Headers:
 
Parameters:
  • scope – The scope of the data identifier.
  • name – The name of the data identifier.
Status Codes:
Returns:

A list of dictionary containing all dataset information.

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:
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:
 
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:
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:
 
Status Codes:
Returns:

Dictionary with DID metadata

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

List all replicas of a data identifier.

Response Headers:
 
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:
Returns:

A dictionary containing all replicas information.

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

Return all rules of a given DID.

Response Headers:
 
Parameters:
  • scope – The scope of the data identifier.
  • name – The name of the data identifier.
Status Codes:
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:
 
Parameters:
  • scope – The scope of the data identifier.
  • name – The name of the data identifier.
Status Codes:
Returns:

A dictionary containing all meta.

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:
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:
 
Status Codes:
Returns:

Dictionary with DID metadata

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:
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:
 
Status Codes:
Returns:

Line separated dictionaries of DIDs