# 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