Skip to content

transfer.process.binding.https.md

Latest commit

 

History

History
271 lines (187 loc) · 10.9 KB

transfer.process.binding.https.md

File metadata and controls

271 lines (187 loc) · 10.9 KB

Transfer Process HTTPS Binding {#transfer-http}

Introduction

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

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.

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.

State Transition Errors

If a client or [=Provider=] makes a request that results in an invalid [=Transfer Process=] 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.

Object Not Found

If the [=Transfer Process=] does not exist, the [=Consumer=] or [=Provider=] MUST return an HTTP 404 (Not Found) response.

Unauthorized Access

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

Provider Path Bindings

Endpoint Method Path
[[[#transfers-get]]] GET /transfers/:providerPid
[[[#transfers-request-post]]] POST /transfers/request
[[[#transfers-providerpid-start-post]]] POST /transfers/:providerPid/start
[[[#transfers-providerpid-completion-post]]] POST /transfers/:providerPid/completion
[[[#transfers-providerpid-termination-post]]] POST /transfers/:providerPid/termination
[[[#transfers-providerpid-suspension-post]]] POST /transfers/:providerPid/suspension

Transfer Process Endpoint {#transfers-get}

Request

A [=Contract Negotiation=] 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 [=Transfer Process=] is found and the client is authorized, the [=Provider=] MUST return an HTTP 200 (OK) response and a body containing the Transfer Process:

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

Predefined states are: REQUESTED, STARTED, SUSPENDED, REQUESTED, COMPLETED, and TERMINATED ( see [[[#transfer-process-states]]]).

Transfer Request Endpoint {#transfers-request-post}

Request

A [=Transfer Process=] 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: ...

  • The callbackAddress property specifies the base endpoint URL where the client receives messages associated with the [=Transfer Process=]. The HTTPS scheme MUST be supported. 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:

Transfer Start Endpoint {#transfers-providerpid-start-post}

Request

The [=Consumer=] can POST a Transfer Start Message to attempt to start a [=Transfer Process=] after it has been suspended:

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

Response

If the [=Transfer Process=]'s state is successfully transitioned, the [=Provider=] MUST return HTTP code 200 (OK). The response body is not specified and clients MAY process it.

Transfer Completion Endpoint {#transfers-providerpid-completion-post}

Request

The [=Consumer=] can POST a Transfer Completion Message to complete a [=Transfer Process=]:

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

Response

If the [=Transfer Process=]'s state is successfully transitioned, the [=Provider=] MUST return HTTP code 200 (OK). The response body is not specified and clients MAY process it.

Transfer Termination Endpoint {#transfers-providerpid-termination-post}

Request

The [=Consumer=] can POST a Transfer Termination Message to terminate a [=Transfer Process=]:

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

Response

If the [=Transfer Process=]'s state is successfully transitioned, the [=Provider=] MUST return HTTP code 200 (OK). The response body is not specified and clients MAY process it.

Transfer Suspension Endpoint {#transfers-providerpid-suspension-post}

Request

The [=Consumer=] can POST a Transfer Suspension Message to suspend a [=Transfer Process=]:

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

Response

If the [=Transfer Process=]'s state is successfully transitioned, the [=Provider=] MUST return HTTP code 200 (OK). The response body is not specified and clients MAY process it.

Consumer Callback Path Bindings

Endpoint Method Path
[[[#transfers-consumerpid-start-post]]] POST /:callback/transfers/:consumerPid/start
[[[#transfers-consumerpid-completion-post]]] POST /:callback/transfers/:consumerPid/completion
[[[#transfers-consumerpid-termination-post]]] POST /:callback/transfers/:consumerPid/termination
[[[#transfers-consumerpid-suspension-post]]] POST /:callback/transfers/:consumerPid/suspension

Prerequisites

All callback paths are relative to the callbackAddress base URL specified in the Transfer Request Message that initiated a [=Transfer Process=]. 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.

The :callback MAY be chosen freely by the implementations.

Transfer Start Endpoint {#transfers-consumerpid-start-post}

Request

The [=Provider=] can POST a Transfer Start Message to indicate the start of a [=Transfer Process=]:

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

Response

If the [=Transfer Process=]'s state is successfully transitioned, the [=Consumer=] MUST return HTTP code 200 (OK). The response body is not specified and clients MAY process it.

Transfer Completion Endpoint {#transfers-consumerpid-completion-post}

Request

The [=Provider=] can POST a Transfer Completion Message to complete a [=Transfer Process=]:

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

Response

If the [=Transfer Process=]'s state is successfully transitioned, the [=Consumer=] MUST return HTTP code 200 (OK). The response body is not specified and clients MAY process it.

Transfer Termination Endpoint {#transfers-consumerpid-termination-post}

Request

The [=Provider=] can POST a Transfer Termination Message to terminate a [=Transfer Process=]:

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

Response

If the [=Transfer Process=]'s state is successfully transitioned, the [=Consumer=] MUST return HTTP code 200 (OK). The response body is not specified and clients MAY process it.

Transfer Suspension Endpoint {#transfers-consumerpid-suspension-post}

Request

The [=Provider=] can POST a Transfer Suspension Message to suspend a [=Transfer Process=]:

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

Response

If the [=Transfer Process=]'s state is successfully transitioned, the [=Consumer=] MUST return HTTP code 200 (OK). The response body is not specified and clients MAY process it.