Binding: HTTPS

This specification defines a RESTful API over HTTPS for the Transfer Process Protocol.

• 1 Introduction

  • 1.1 Prerequisites

  • 1.2 Transfer Error

    • 1.2.1 State Transition Errors

    • 1.2.2 Object Not Found

    • 1.2.3 Unauthorized Access

• 2 Provider Path Bindings

  • 2.1 The transfers Endpoint (Provider-side)

  • 2.2 The transfers/request Endpoint (Provider-side)

  • 2.3 The transfers/:providerPid/start Endpoint (Provider-side)

  • 2.4 The transfers/:providerPid/completion Endpoint (Provider-side)

  • 2.5 The transfers/:providerPid/termination Endpoint (Provider-side)

  • 2.6 The transfers/:providerPid/suspension Endpoint (Provider-side)

• 3 Consumer Callback Path Bindings

  • 3.1 Prerequisites

  • 3.2 The transfers/:consumerPid/start Endpoint (Consumer-side)

  • 3.3 The transfers/:consumerPid/completion Endpoint (Consumer-side)

  • 3.4 The transfers/:consumerPid/termination Endpoint (Consumer-side)

  • 3.5 The transfers/:consumerPid/suspension Endpoint (Consumer-side)

1 Introduction

1.1 Prerequisites

1. The <base> notation indicates the base URL for a Connector endpoint. For example, if the scheme is https and the full hostname is connector.example.com, the URL <base>/transfers/request will map to https://connector.example.com/transfers/request.

2. All request and response messages must use the application/json media type. Derived media types, e.g., application/ld+json may be exposed in addition.

1.2 Transfer Error

In the event of a client request error, the Connector must return an appropriate HTTP 4xx client error code. If an error body is returned it must be a Transfer Error.

1.2.1 State Transition Errors

If a client or Provider makes a request that results in an invalid Transfer Process (TP) state transition as defined by the Transfer Process Protocol, it must return an HTTP code 400 (Bad Request) with a Transfer Error in the response body.

1.2.2 Object Not Found

If the TP does not exist, the Consumer or Provider must return an HTTP 404 (Not Found) response.

1.2.3 Unauthorized Access

If the client is not authorized, the Consumer or Provider must return an HTTP 404 (Not Found) response.

2 Provider Path Bindings

Endpoint	Method	Description
https://provider.com/transfers/:providerPid	GET	Section 2.1.1
https://provider.com/transfers/request	POST	Section 2.2.1
https://provider.com/transfers/:providerPid/start	POST	Section 2.3.1
https://provider.com/transfers/:providerPid/completion	POST	Section 2.4.1
https://provider.com/transfers/:providerPid/termination	POST	Section 2.5.1
https://provider.com/transfers/:providerPid/suspension	POST	Section 2.6.1

2.1 The transfers Endpoint (Provider-side)

2.1.1 GET

Request

A CN can be accessed by a Consumer or Provider sending a GET request to transfers/:providerPid:

GET https://provider.com/transfers/:providerPid

Authorization: ...

Response

If the TP is found and the client is authorized, the Provider must return an HTTP 200 (OK) response and a body containing the Transfer Process:

{
  "@context":  "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:TransferProcess",
  "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
  "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
  "dspace:state": "dspace:REQUESTED"
} 

Predefined states are: REQUESTED, STARTED, SUSPENDED, REQUESTED, COMPLETED, and TERMINATED.

2.2 The transfers/request Endpoint (Provider-side)

2.2.1 POST

Request

A TP is started and placed in the REQUESTED state when a Consumer POSTs a Transfer Request Message to transfers/request:

POST https://provider.com/transfers/request

Authorization: ...

{
 "@context":  "https://w3id.org/dspace/2024/1/context.json",
 "@type": "dspace:TransferRequestMessage",
 "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
 "dspace:agreementId": "urn:uuid:e8dc8655-44c2-46ef-b701-4cffdc2faa44",
 "dct:format": "example:HTTP_PUSH",
 "dspace:dataAddress": {
   "@type": "dspace:DataAddress",
   "dspace:endpointType": "https://w3id.org/idsa/v4.1/HTTP",
   "dspace:endpoint": "http://example.com",
   "dspace:endpointProperties": [
     {
       "@type": "dspace:EndpointProperty",
       "dspace:name": "authorization",
       "dspace:value": "TOKEN-ABCDEFG"
     },
     {
       "@type": "dspace:EndpointProperty",
       "dspace:name": "authType",
       "dspace:value": "bearer"
     }
   ]
 },
 "dspace:callbackAddress": "https://......"
}

• The callbackAddress property specifies the base endpoint URL where the client receives messages associated with the TP. Support for the HTTPS scheme is required. Implementations may optionally support other URL schemes.

• Callback messages will be sent to paths under the base URL as described by this specification. Note that Providers should properly handle the cases where a trailing / is included with or absent from the callbackAddress when resolving full URL.

Response

The Provider must return an HTTP 201 (Created) response with a body containing the Transfer Process:

{
  "@context":  "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:TransferProcess",
  "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
  "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
  "dspace:state": "dspace:REQUESTED"
}

2.3 The transfers/:providerPid/start Endpoint (Provider-side)

2.3.1 POST

Request

The Consumer can POST a Transfer Start Message to attempt to start a TP after it has been suspended:

POST https://provider.com/transfers/:providerPid/start

Authorization: ...

{
 "@context":  "https://w3id.org/dspace/2024/1/context.json",
 "@type": "dspace:TransferStartMessage",
 "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
 "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
 "dspace:dataAddress": {
   "@type": "dspace:DataAddress",
   "dspace:endpointType": "https://w3id.org/idsa/v4.1/HTTP",
   "dspace:endpoint": "http://example.com",
   "dspace:endpointProperties": [
     {
       "@type": "dspace:EndpointProperty",
       "dspace:name": "authorization",
       "dspace:value": "TOKEN-ABCDEFG"
     },
     {
       "@type": "dspace:EndpointProperty",
       "dspace:name": "authType",
       "dspace:value": "bearer"
     }
   ]
 }
}

Response

If the TP's state is successfully transitioned, the Provider must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.

2.4 The transfers/:providerPid/completion Endpoint (Provider-side)

2.4.1 POST

Request

The Consumer can POST a Transfer Completion Message to complete a TP:

POST https://provider.com/transfers/:providerPid/completion

Authorization: ...

{
 "@context":  "https://w3id.org/dspace/2024/1/context.json",
 "@type": "dspace:TransferCompletionMessage",
 "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
 "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833"
}

Response

If the TP's state is successfully transitioned, the Provider must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.

2.5 The transfers/:providerPid/termination Endpoint (Provider-side)

2.5.1 POST

Request

The Consumer can POST a Transfer Termination Message to terminate a TP:

POST https://provider.com/transfers/:providerPid/termination

Authorization: ...

{
 "@context":  "https://w3id.org/dspace/2024/1/context.json",
 "@type": "dspace:TransferTerminationMessage",
 "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
 "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
 "dspace:code": "...",
 "dspace:reason": [
   ...
 ]
}

Response

If the TP's state is successfully transitioned, the Provider must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.

2.6 The transfers/:providerPid/suspension Endpoint (Provider-side)

2.6.1 POST

Request

The Consumer can POST a Transfer Suspension Message to suspend a TP:

POST https://provider.com/transfers/:providerPid/suspension

Authorization: ...

{
 "@context":  "https://w3id.org/dspace/2024/1/context.json",
 "@type": "dspace:TransferSuspensionMessage",
 "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
 "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
 "dspace:code": "...",
 "dspace:reason": [
   ...
 ]
}

Response

If the TP's state is successfully transitioned, the Provider must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.

3 Consumer Callback Path Bindings

Endpoint	Method	Description
https://consumer.com/:callback/transfers/:consumerPid/start	POST	Section 3.2.1
https://consumer.com/:callback/transfers/:consumerPid/completion	POST	Section 3.3.1
https://consumer.com/:callback/transfers/:consumerPid/termination	POST	Section 3.4.1
https://consumer.com/:callback/transfers/:consumerPid/suspension	POST	Section 3.5.1

3.1 Prerequisites

All callback paths are relative to the callbackAddress base URL specified in the Transfer Request Message that initiated a TP. For example, if the callbackAddress is specified as https://consumer.com/callback and a callback path binding is transfers/:consumerPid/start, the resolved URL will be https://consumer.com/callback/transfers/:consumerPid/start.

3.2 The transfers/:consumerPid/start Endpoint (Consumer-side)

3.2.1 POST

Request

The Provider can POST a Transfer Start Message to indicate the start of a TP:

POST https://consumer.com/:callback/transfers/:consumerPid/start

Authorization: ...

{
 "@context":  "https://w3id.org/dspace/2024/1/context.json",
 "@type": "dspace:TransferStartMessage",
 "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
 "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
 "dspace:dataAddress": {
   "@type": "dspace:DataAddress",
   "dspace:endpointType": "https://w3id.org/idsa/v4.1/HTTP",
   "dspace:endpoint": "http://example.com",
   "dspace:endpointProperties": [
     {
       "@type": "dspace:EndpointProperty",
       "dspace:name": "authorization",
       "dspace:value": "TOKEN-ABCDEFG"
     },
     {
       "@type": "dspace:EndpointProperty",
       "dspace:name": "authType",
       "dspace:value": "bearer"
     }
   ]
 }
}

Response

If the TP's state is successfully transitioned, the Consumer must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.

3.3 The transfers/:consumerPid/completion Endpoint (Consumer-side)

3.3.1 POST

Request

The Provider can POST a Transfer Completion Message to complete a TP:

POST https://consumer.com/:callback/transfers/:consumerPid/completion

Authorization: ...

{
 "@context":  "https://w3id.org/dspace/2024/1/context.json",
 "@type": "dspace:TransferCompletionMessage",
 "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
 "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833"
}

Response

If the TP's state is successfully transitioned, the Consumer must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.

3.4 The transfers/:consumerPid/termination Endpoint (Consumer-side)

3.4.1 POST

Request

The Provider can POST a Transfer Termination Message to terminate a TP:

POST https://consumer.com/:callback/transfers/:consumerPid/termination

Authorization: ...

{
 "@context":  "https://w3id.org/dspace/2024/1/context.json",
 "@type": "dspace:TransferTerminationMessage",
 "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
 "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
 "dspace:code": "...",
 "dspace:reason": [
   ...
 ]
}

Response

If the TP's state is successfully transitioned, the Consumer must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.

3.5 The transfers/:consumerPid/suspension Endpoint (Consumer-side)

3.5.1 POST

Request

The Provider can POST a Transfer Suspension Message to suspend a TP:

POST https://consumer.com/:callback/transfers/:consumerPid/suspension

Authorization: ...

{
 "@context":  "https://w3id.org/dspace/2024/1/context.json",
 "@type": "dspace:TransferSuspensionMessage",
 "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
 "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
 "dspace:code": "...",
 "dspace:reason": [
   ...
 ]
}

Response

If the TP's state is successfully transitioned, the Consumer must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.