diff --git a/IETF-RFC.md b/IETF-RFC.md index a8d1dea..90660f2 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -1015,6 +1015,36 @@ They could give the Receiving Party the option to accept or reject the share, or add the share automatically and only send an informational notification that this happened. +# Request for a Share + +If the Receiving Party knows of a resource that has not yet +been shared, the Receiving Party MAY make an HTTP POST request + +* to the `/request-share` path in the Sending Server's OCM API +* using `application/json` as the `Content-Type` HTTP request + header +* its request body containing a JSON document representing an + object with the fields as described below +* using TLS +* using httpsig [RFC9421] + +## Fields + +* REQUIRED sender (string) + OCM Address of the user who will be requested to share + the resource. +* REQUIRED shareWith (string) + OCM Address of the user, group or federation that wants to + receive a share of the resource. + Example: "51dc30ddc473d43a6011e9ebba6ca770@geant.org" +* REQUIRED shareId (string) + A unique identifier for the resource. + Example: 1234567890abcdef + +After receiving a request for a Share, the Sending Party MAY +send a Share Creation Notification to the Receiving Party +using the OCM address in the shareWith field. + # Share Acceptance Notification diff --git a/spec.yaml b/spec.yaml index f1fa552..d5d6e3c 100644 --- a/spec.yaml +++ b/spec.yaml @@ -36,6 +36,54 @@ paths: application/json: schema: $ref: "#/components/schemas/Discovery" + /request-share: + post: + summary: Request access to a share + description: > + This endpoint is used to request access to a share. + The request MUST contain the share ID and the OCM address of the party + who wants to receive the share. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RequestShare" + description: The JSON object to request access to a share. + required: true + responses: + "201": + description: > + Consumer successfully received request. + "400": + description: > + Bad request due to invalid parameters, e.g. when `shareId` is missing. + content: + application/json: + schema: + $ref: "#/components/schemas/400" + "501": + description: The server doesn't support requesting shares. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "503": + description: The server is temporary unavailable (e.g. due to planned + maintenance). + headers: + Retry-After: + description: > + Indication for the client when the service could be requested + again in HTTP Date format as used by the Internet Message + Format [RFC5322] (e.g. `Wed, 21 Oct 2015 07:28:00 GMT`) or the + number of seconds (e.g. 3000 if you the service is expected to + be available again within 50 minutes). + schema: + type: string + content: + application/json: + schema: + $ref: "#/components/schemas/Error" /shares: post: summary: Share Creation Notification endpoint @@ -843,6 +891,29 @@ components: type: string description: Name of the Invite Sender. example: John Doe + RequestShare: + type: object + required: + - sender + - shareWith + - shareId + properties: + sender: + type: string + description: > + OCM Address of the user who will be requested to share + the resource. + example: 527bd5b5d689e2c32ae974c6229ff785@apiwise.nl + shareWith: + type: string + description: > + OCM Address of the user, group or federation that + wants to receive a share of the resource. + example: 51dc30ddc473d43a6011e9ebba6ca770@geant.org + shareId: + type: string + description: A unique identifier for the resource. + example: 1234567890abcdef TokenRequest: type: object required: