Binding: HTTPS
This specification defines a RESTful API over HTTPS for the Transfer Process Protocol.
1 Introduction
1.1 Prerequisites
The
<base>
notation indicates the base URL for a Connector endpoint. For example, if the scheme ishttps
and the full hostname isconnector.example.com
, the URL<base>/transfers/request
will map tohttps://connector.example.com/transfers/request
.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 |
| Section 2.1.1 |
https://provider.com/transfers/request |
| Section 2.2.1 |
https://provider.com/transfers/:providerPid/start |
| Section 2.3.1 |
https://provider.com/transfers/:providerPid/completion |
| Section 2.4.1 |
https://provider.com/transfers/:providerPid/termination |
| Section 2.5.1 |
https://provider.com/transfers/:providerPid/suspension |
| Section 2.6.1 |
2.1 The transfers
Endpoint (Provider-side)
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
:
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:
Predefined states are: REQUESTED
, STARTED
, SUSPENDED
, REQUESTED
, COMPLETED
, and TERMINATED
.
2.2 The transfers/request
Endpoint (Provider-side)
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
:
The
callbackAddress
property specifies the base endpointURL
where the client receives messages associated with the TP. Support for theHTTPS
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 thecallbackAddress
when resolving full URL.
Response
The Provider must return an HTTP 201 (Created) response with a body containing the Transfer Process:
2.3 The transfers/:providerPid/start
Endpoint (Provider-side)
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:
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)
transfers/:providerPid/completion
Endpoint (Provider-side)2.4.1 POST
Request
The Consumer can POST a Transfer Completion Message to complete a TP:
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)
transfers/:providerPid/termination
Endpoint (Provider-side)2.5.1 POST
Request
The Consumer can POST a Transfer Termination Message to terminate a TP:
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)
transfers/:providerPid/suspension
Endpoint (Provider-side)2.6.1 POST
Request
The Consumer can POST a Transfer Suspension Message to suspend a TP:
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 |
| Section 3.2.1 |
https://consumer.com/:callback/transfers/:consumerPid/completion |
| Section 3.3.1 |
https://consumer.com/:callback/transfers/:consumerPid/termination |
| Section 3.4.1 |
https://consumer.com/:callback/transfers/:consumerPid/suspension |
| 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)
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:
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)
transfers/:consumerPid/completion
Endpoint (Consumer-side)3.3.1 POST
Request
The Provider can POST a Transfer Completion Message to complete a TP:
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)
transfers/:consumerPid/termination
Endpoint (Consumer-side)3.4.1 POST
Request
The Provider can POST a Transfer Termination Message to terminate a TP:
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)
transfers/:consumerPid/suspension
Endpoint (Consumer-side)3.5.1 POST
Request
The Provider can POST a Transfer Suspension Message to suspend a TP:
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.
Last updated