Skip to content

Latest commit

 

History

History
470 lines (337 loc) · 21 KB

contract.negotiation.binding.https.md

File metadata and controls

470 lines (337 loc) · 21 KB

Contract Negotiation HTTPS Binding

This specification defines a RESTful API over HTTPS for the Contract Negotiation Protocol.

1 Introduction

1.1 Prerequisites

  1. The <base> notation indicates the base URL for a Connector endpoint. For example, if the base Connector URL is connector.example.com, the URL https://<base>/negotiations/request will map to https//connector.example.com/negotiation/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 Contract Negotiation 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 Contract Negotiation Error.

1.2.1 State Transition Errors

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

1.2.2 Object Not Found

If the Contract Negotiation (CN) 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.

1.3 Authorization

All requests should use the Authorization header to include an authorization token. The semantics of such tokens are not part of this specification. The Authorization HTTP header is optional if the Connector does not require authorization.

2 Provider Path Bindings

Endpoint Method Description
https://provider.com/negotiations/:providerPid GET Section 2.1.1
https://provider.com/negotiations/request POST Section 2.2.1
https://provider.com/negotiations/:providerPid/request POST Section 2.3.1
https://provider.com/negotiations/:providerPid/events POST Section 2.4.1
https://provider.com/negotiations/:providerPid/agreement/verification POST Section 2.5.1
https://provider.com/negotiations/:providerPid/termination POST Section 2.6.1

2.1 The negotiations Endpoint (Provider-side)

2.1.1 GET

Request

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

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

Authorization: ...
Response

If the CN is found and the client is authorized, the Provider must return an HTTP 200 (OK) response and a body containing the Contract Negotiation:

{
  "@context": "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:ContractNegotiation",
  "dspace:providerPid": "urn:uuid:dcbf434c-eacf-4582-9a02-f8dd50120fd3",
  "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
  "dspace:state" :"REQUESTED"
}

Predefined states are: REQUESTED, OFFERED, ACCEPTED, AGREED, VERIFIED, FINALIZED, and TERMINATED (see here.

2.2 The negotiations/request Endpoint (Provider-side)

2.2.1 POST

Request

A CN is started and placed in the REQUESTED state when a Consumer POSTs an initiating Contract Request Message to negotiations/request:

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

Authorization: ...

{
  "@context": "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:ContractRequestMessage",
  "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
  "dspace:offer": {
    "@type": "odrl:Offer",
    "@id": "...",
    "target": "urn:uuid:3dd1add8-4d2d-569e-d634-8394a8836a88"
  },
  "dspace:callbackAddress": "https://..."
}

  • The callbackAddress property specifies the base endpoint URL where the client receives messages associated with the CN. 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 Contract Negotiation:

{
  "@context": "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:ContractNegotiation",
  "dspace:providerPid": "urn:uuid:dcbf434c-eacf-4582-9a02-f8dd50120fd3",
  "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
  "dspace:state" :"REQUESTED"
}

2.3 The negotiations/:providerPid/request Endpoint (Provider-side)

2.3.1 POST

Request

A Consumer may make an Offer by POSTing a Contract Request Message to negotiations/:providerPid/request:

POST https://provider.com/negotiations/:providerPid/request

Authorization: ...

{
  "@context": "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:ContractRequestMessage",
  "dspace:providerPid": "urn:uuid:dcbf434c-eacf-4582-9a02-f8dd50120fd3",
  "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
  "dspace:offer": {
    "@type": "odrl:Offer",
    "@id": "...",
    "target": "urn:uuid:3dd1add8-4d2d-569e-d634-8394a8836a88"
  }
}
Response

If the message is successfully processed, the Provider must return an HTTP 200 (OK) response. The response body is not specified and clients are not required to process it.

2.4 The negotiations/:providerPid/events Endpoint (Provider-side)

2.4.1 POST

Request

A Consumer can POST a Contract Negotiation Event Message to negotiations/:providerPid/events to accept the current Provider's Offer.

POST https://provider.com/negotiations/:providerPid/events

Authorization: ...

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

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

If the current Offer was created by the Consumer, the Provider must return an HTTP code 400 (Bad Request) with a Contract Negotiation Error in the response body.

2.5 The negotiations/:providerPid/agreement/verification Endpoint (Provider-side)

2.5.1 POST

Request

The Consumer can POST a Contract Agreement Verification Message to verify an Agreement.

POST https://provider.com/negotiations/:providerPid/agreement/verification

Authorization: ...

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

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

2.6 The negotiations/:providerPid/termination Endpoint (Provider-side)

2.6.1 POST

Request

The Consumer can POST a Contract Negotiation Termination Message to terminate a CN.

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

Authorization: ...

{
  "@context":  "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:ContractNegotiationTerminationMessage",
  "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 CN'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/negotiations/offers POST Section 3.2.1
https://consumer.com/:callback/negotiations/:consumerPid/offers POST Section 3.3.1
https://consumer.com/:callback/negotiations/:consumerPid/agreement POST Section 3.4.1
https://consumer.com/:callback/negotiations/:consumerPid/events POST Section 3.5.1
https://consumer.com/:callback/negotiations/:consumerPid/termination POST Section 3.6.1

Note: The :callback can be chosen freely by the implementations.

3.1 Prerequisites

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

3.2 The negotiations/offers Endpoint (Consumer-side)

3.2.1 POST

Request

A CN is started and placed in the OFFERED state when a Provider POSTs a Contract Offer Message to negotiations/offers:

POST https://consumer.com/negotiations/offers

Authorization: ...

{
  "@context": "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:ContractOfferMessage",
  "dspace:providerPid": "urn:uuid:dcbf434c-eacf-4582-9a02-f8dd50120fd3",
  "dspace:offer": {
    "@type": "odrl:Offer",
    "@id": "...",
    "target": "urn:uuid:3dd1add8-4d2d-569e-d634-8394a8836a88"
  },
  "dspace:callbackAddress": "https://..."
}

  • The callbackAddress property specifies the base endpoint URL where the client receives messages associated with the CN. 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 Consumers should properly handle the cases where a trailing / is included with or absent from the callbackAddress when resolving full URL.

Response

The Consumer must return an HTTP 201 (Created) response with a body containing the Contract Negotiation:

{
  "@context": "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:ContractNegotiation",
  "dspace:providerPid": "urn:uuid:dcbf434c-eacf-4582-9a02-f8dd50120fd3",
  "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
  "dspace:state" :"OFFERED"
}

3.3 The negotiations/:consumerPid/offers Endpoint (Consumer-side)

3.3.1 POST

Request

A Provider may make an Offer by POSTing a Contract Offer Message to the negotiations/:consumerPid/offers callback:

POST https://consumer.com/:callback/negotiations/:consumerPid/offers

Authorization: ...

{
  "@context":  "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:ContractOfferMessage",
  "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
  "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
  "dspace:offer": {
    "@type": "odrl:Offer",
    "@id": "urn:uuid:6bcea82e-c509-443d-ba8c-8eef25984c07",
    "odrl:target": "urn:uuid:3dd1add8-4d2d-569e-d634-8394a8836a88",
    "dspace:providerId": "urn:tsdshhs636378",
    "dspace:consumerId": "urn:jashd766",
    ...
  },
  "dspace:callbackAddress": "https://......"
}
Response

If the message is successfully processed, the Consumer must return an HTTP 200 (OK) response. The response body is not specified and clients are not required to process it.

3.4 The negotiations/:consumerPid/agreement Endpoint (Consumer-side)

3.4.1 POST

Request

The Provider can POST a Contract Agreement Message to the negotiations/:consumerPid/agreement callback to create an Agreement.

POST https://consumer.com/:callback/negotiations/:consumerPid/agreement

Authorization: ...

{
  "@context":  "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:ContractAgreementMessage",
  "dspace:providerPid": "urn:uuid:a343fcbf-99fc-4ce8-8e9b-148c97605aab",
  "dspace:consumerPid": "urn:uuid:32541fe6-c580-409e-85a8-8a9a32fbe833",
  "dspace:agreement": {
    "@id": "urn:uuid:e8dc8655-44c2-46ef-b701-4cffdc2faa44",
    "@type": "odrl:Agreement",
    "odrl:target": "urn:uuid:3dd1add4-4d2d-569e-d634-8394a8836d23",
    "dspace:timestamp": "2023-01-01T01:00:00Z",
    "dspace:providerId": "urn:tsdshhs636378",
    "dspace:consumerId": "urn:jashd766",
    ...
  },
  "dspace:callbackAddress": "https://......"
}
Response

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

3.5 The negotiations/:consumerPid/events Endpoint (Consumer-side)

3.5.1 POST

Request

A Provider can POST a Contract Negotiation Event Message to the negotiations/:consumerPid/events callback with an eventType of FINALIZED to finalize an Agreement.

POST https://consumer.com/:callback/negotiations/:consumerPid/events

Authorization: ...

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

If the CN'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.6 The negotiations/:consumerPid/termination Endpoint (Consumer-side)

3.6.1 POST

Request

The Provider can POST a Contract Negotiation Termination Message to terminate a CN.

POST https://consumer.com/negotiations/:consumerPid/termination

Authorization: ...

{
  "@context":  "https://w3id.org/dspace/2024/1/context.json",
  "@type": "dspace:ContractNegotiationTerminationMessage",
  "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 CN'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.