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: - Content-Type – application/x-json-stream
Query Parameters: - type – the DID type.
Status Codes: - 200 OK – DIDs found
- 401 Unauthorized – Invalid Auth Token
- 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
- 409 Conflict – DID already exists
- 500 Internal Server Error – Database Exception
-
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=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: - Content-Type – application/x-json-stream
Status Codes: - 200 OK – DIDs found
- 401 Unauthorized – Invalid Auth Token
- 404 Not Found – Invalid key in filters
- 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
- 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
- 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
- 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
- 500 Internal Server Error – Database Exception
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: - 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
-
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
Returns: Dictionary with DID metadata
-
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
- 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
- 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
- 500 Internal Server Error – Database Exception
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: - 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/json
Status Codes: - 200 OK – DID found
- 401 Unauthorized – Invalid Auth Token
- 404 Not Found – Scope not found
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: - 200 OK – DIDs successfully detached
- 401 Unauthorized – Invalid Auth Token
- 404 Not Found – DID not found
- 500 Internal Server Error – Database Exception
-
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
Returns: Line separated dictionaries of DIDs