Replica Rest API

Overview

Resource	Operation	Description
BadPFNs	POST /replicas/bad/pfns	Declare bad replicas.
BadReplicasStates	GET /replicas/bad/states	List bad replicas.
	POST /replicas/bad	Declare bad replicas.
BadReplicasSummary	GET /replicas/bad/summary	List bad replicas by incident.
DatasetReplicas	GET /replicas/(scope)/(name)/datasets	List dataset replicas.
DatasetReplicasBulk	POST /replicas/datasets_bulk	List dataset replicas (bulk).
ListReplicas	POST /replicas/list	List all replicas for did.
Replicas	GET /replicas/(scope)/(name)	List all replicas for did
	DELETE /replicas/	Delete replica at RSE.
	POST /replicas/	create replicas at RSE
	PUT /replicas/	update replicas state.
ReplicasDIDs	POST /replicas/dids	List DIDs for replicas.
ReplicasRSE	GET /replicas/rse/(rse)	List dataset replicas per RSE.
SuspiciousReplicas	POST /replicas/suspicious	Declare suspicious replicas.
Tombstone	POST /replicas/tombstone	Set a tombstone on a list of replicas.

Details

GET /replicas/bad/summary

Return a summary of the bad replicas by incident.

Query Parameters

• rse_expression – The RSE expression.

• from_date – The start date.

• to_date – The end date.

Response Headers

• Content-Type – application/x-json-stream

Status Codes

• 200 OK – OK.

• 401 Unauthorized – Invalid auth token.

• 406 Not Acceptable – Not Acceptable.

• 500 Internal Server Error – Internal Error.

Returns

List of bad replicas by incident.

GET /replicas/bad/states

List the bad or suspicious replicas by states.

Query Parameters

• state – The state of the file (SUSPICIOUS or BAD).

• rse – The RSE name.

• younger_than – date in format “%Y-%m-%dT%H:%M:%S.%f” to select bad replicas younger than this date.

• older_than – date in format “%Y-%m-%dT%H:%M:%S.%f” to select bad replicas older than this date.

• limit – The maximum number of replicas returned.

• list_pfns – Flag to include pfns.

Response Headers

• Content-Type – application/x-json-stream

Status Codes

• 200 OK – OK.

• 401 Unauthorized – Invalid auth token.

• 406 Not Acceptable – Not Acceptable.

• 500 Internal Server Error – Internal Error.

Returns

List of dicts of bad file replicas.

POST /replicas/bad/pfns

Declare a list of bad PFNs.

Request JSON Object

• pfns (string) – The list of PFNs.

• reason (string) – The reason of the loss.

• state (string) – The state is eiher BAD, SUSPICIOUS or TEMPORARY_UNAVAILABLE.

• expires_at (string) – The expiration date. Only apply to TEMPORARY_UNAVAILABLE.

Response Headers

• Content-Type – application/x-json-string

Status Codes

• 201 Created – Created.

• 400 Bad Request – Cannot decode json parameter list.

• 401 Unauthorized – Invalid auth token.

• 404 Not Found – Replica not found.

• 500 Internal Server Error – Internal Error.

Returns

A list of not successfully declared files.

POST /replicas/datasets_bulk

List dataset replicas for multiple DIDs.

Request JSON Object

• dids (list) – List of DIDs for querying the datasets.

Response Headers

• Content-Type – application/x-json-stream

Status Codes

• 200 OK – OK.

• 400 Bad Request – Bad Request.

• 401 Unauthorized – Invalid auth token.

• 406 Not Acceptable – Not Acceptable.

• 500 Internal Server Error – Internal Error.

Returns

A dictionary containing all replicas information.

POST /replicas/suspicious

Declare a list of suspicious replicas.

Request JSON Object

• pfns (string) – The list of PFNs.

• reason (string) – The reason of the loss.

Response Headers

• Content-Type – application/x-json-string

Status Codes

• 201 Created – Created.

• 400 Bad Request – Cannot decode json parameter list.

• 401 Unauthorized – Invalid auth token.

• 404 Not Found – Replica not found.

• 500 Internal Server Error – Internal Error.

Returns

A list of not successfully declared files.

POST /replicas/tombstone

Set a tombstone on a list of replicas.

Request JSON Object

• replicas (string) – list fo replicas

Response Headers

• Content-Type – application/x-json-string

Status Codes

• 201 Created – Created.

• 401 Unauthorized – Invalid auth token.

• 404 Not Found – ReplicaNotFound.

• 500 Internal Server Error – Internal Error.

POST /replicas/list

List all replicas for data identifiers.

Request Headers

• HTTP_ACCEPT – application/metalink4+xml

Query Parameters

• schemes – A list of schemes to filter the replicas.

• sort – Requested sorting of the result, e.g., ‘geoip’, ‘closeness’, ‘dynamic’, ‘ranking’.

Request JSON Object

• dids (list) – list of DIDs.

• schemes (list) – A list of schemes to filter the replicas.

• unavailable (bool) – Also include unavailable replicas.

• all_states (bool) – Return all replicas whatever state they are in. Adds an extra ‘states’ entry in the result dictionary.

• rse_expression (string) – The RSE expression to restrict on a list of RSEs.

• client_location (dict) – Client location dictionary for PFN modification {‘ip’, ‘fqdn’, ‘site’}.

• sort (bool) – Requested sorting of the result, e.g., ‘geoip’, ‘closeness’, ‘dynamic’, ‘ranking’.

• domain (string) – The network domain for the call, either None, ‘wan’ or ‘lan’. None is fallback to ‘wan’, ‘all’ is both [‘lan’,’wan’]

Response Headers

• Content-Type – application/x-json-stream

• Content-Type – application/metalink4+xml

Status Codes

• 200 OK – OK.

• 400 Bad Request – Cannot decode json parameter list.

• 401 Unauthorized – Invalid auth token.

• 404 Not Found – DID not found.

• 406 Not Acceptable – Not Acceptable.

• 500 Internal Server Error – Internal Error.

Returns

A dictionary containing all replicas information.

Returns

A metalink description of replicas if metalink(4)+xml is specified in Accept:

POST /replicas/dids

List the DIDs associated to a list of replicas.

Request JSON Object

• pfns (string) – The list of PFNs.

• rse (string) – The RSE name.

Response Headers

• Content-Type – application/x-json-string

Status Codes

• 200 OK – OK.

• 400 Bad Request – Cannot decode json parameter list.

• 406 Not Acceptable – Not Acceptable.

• 500 Internal Server Error – Internal Error.

Returns

A list of dictionaries containing the mapping PFNs to DIDs.

POST /replicas/bad

Declare a list of bad replicas.

Request JSON Object

• pfns (string) – The list of PFNs.

• reason (string) – The reason of the loss.

Response Headers

• Content-Type – application/x-json-string

Status Codes

• 201 Created – Created.

• 400 Bad Request – Cannot decode json parameter list.

• 401 Unauthorized – Invalid auth token.

• 404 Not Found – Replica not found.

• 500 Internal Server Error – Internal Error.

Returns

A list of not successfully declared files.

GET /replicas/(scope)/(name)

List all replicas for data identifiers.

HTTP Success:

200 OK

HTTP Error:

401 Unauthorized 500 InternalError

Request Headers

• HTTP_ACCEPT – application/metalink4+xml

Parameters

• scope – data identifier scope.

• name – data identifier name.

Response Headers

• Content-Type – application/x-json-stream

• Content-Type – application/metalink4+xml

Status Codes

• 200 OK – OK.

• 401 Unauthorized – Invalid auth token.

• 404 Not Found – DID not found.

• 406 Not Acceptable – Not Acceptable.

• 500 Internal Server Error – Internal Error.

Returns

A dictionary containing all replicas information.

Returns

A metalink description of replicas if metalink(4)+xml is specified in Accept:

DELETE /replicas/

Delete file replicas at a given RSE.

Request JSON Object

• rse (string) – The RSE name.

• files (list) – list of dicts with ‘scope’, ‘name’.

• ignore_availability (bool) – Flag to ignore the RSE blacklisting.

Status Codes

• 200 OK – Replica successfully deleted.

• 400 Bad Request – Cannot decode json parameter list.

• 401 Unauthorized – Invalid auth token.

• 404 Not Found – RSE not found.

• 404 Not Found – Replica not found.

• 500 Internal Server Error – Internal Error.

POST /replicas/

Create file replicas at a given RSE.

Request JSON Object

• rse (string) – The RSE name.

• files (list) – list of dicts with ‘scope’, ‘name’, ‘bytes’, ‘meta’ and ‘adler32’.

• ignore_availability (bool) – Flag to ignore the RSE blacklisting.

Status Codes

• 201 Created – Replica Successfully created.

• 400 Bad Request – Invalid Path.

• 401 Unauthorized – Invalid auth token.

• 404 Not Found – RSE not found.

• 409 Conflict – Replica already exists.

• 409 Conflict – DID already exists.

• 503 Service Unavailable – Resource Temporary Unavailable.

PUT /replicas/

Update a file replicas state at a given RSE.

Request JSON Object

• rse (string) – The RSE name.

• files (list) – list of dicts with ‘scope’, ‘name’ and ‘state’.

Status Codes

• 201 Created – Replica successfully updated.

• 400 Bad Request – Cannot decode json parameter list.

• 401 Unauthorized – Invalid auth token.

• 500 Internal Server Error – Internal Error.

GET /replicas/rse/(rse)

List dataset replicas per RSE.

Response Headers

• Content-Type – application/x-json-stream

Status Codes

• 200 OK – OK.

• 401 Unauthorized – Invalid auth token.

• 406 Not Acceptable – Not Acceptable.

• 500 Internal Server Error – Internal Error.

Returns

A dictionary containing all replicas on the RSE.

GET /replicas/(scope)/(name)/datasets

List dataset replicas.

Query Parameters

• deep – Flag to ennable lookup at the file level.

Response Headers

• Content-Type – application/x-json-stream

Status Codes

• 200 OK – OK.

• 401 Unauthorized – Invalid auth token.

• 406 Not Acceptable – Not Acceptable.

• 500 Internal Server Error – Internal Error.

Returns

A dictionary containing all replicas information.