Skip to content

Invitation workflow for OCM #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
LovisaLugnegard wants to merge 11 commits into from
Closed

Invitation workflow for OCM #41

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
dcdc02e
Add endpoints for accept and forward invite
LovisaLugnegard Apr 1, 2020
7fe8bc6
ocm: enhance invitation flow
labkode Apr 15, 2020
634561d
ocm: fix
labkode Apr 15, 2020
50540d1
fix leading slash
labkode Apr 15, 2020
2989d9d
Merge pull request #1 from labkode/enhance-ocm-invite
LovisaLugnegard Apr 15, 2020
c57129b
Smaller copy updates
LovisaLugnegard Apr 15, 2020
8fdc1d9
Minor updates in the invites API
LovisaLugnegard Apr 17, 2020
a840caf
Fix typos
LovisaLugnegard Apr 17, 2020
98e8e4d
Add name and email to invites/accept request
ishank011 Apr 27, 2020
8fe2fe3
Merge pull request #2 from LovisaLugnegard/add_invite_accept_params
ishank011 Apr 28, 2020
f2d17c0
Improve description
LovisaLugnegard Jun 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 80 additions & 1 deletion spec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -355,6 +355,47 @@ paths:
type: string
schema:
$ref: "#/definitions/Error"
/invites/forward:
Copy link
Contributor

@michielbdejong michielbdejong Aug 6, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Who forwards the invitation when this end-point is called, and from where to where?

Copy link
Contributor

@michielbdejong michielbdejong Aug 6, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC from https://www.youtube.com/watch?v=TnlUOG3lOu4, the flow would be as follows, if Alice at server A invites Bob at server B:

  • Alice instructs A to send an invite to "Bob@B"
    • A changes state, "invite sent from Alice to Bob@B"
    • A calls B/invites/forward
    • B changes state, "invite received from Alice@A to Bob"
  • B notifies Bob (this is the "forwarding", right?)
  • Bob instructs B to accept the invitation
    • B changes state, "invite from Alice@A to Bob accepted"
    • B calls A/invites/accept
    • A changes state, "invite from Alice to Bob@B accepted"

If this is correct, then I think the summary and description should reflect that it is B who forwards the invite from A (or effectively from Alice@A) to Bob?

Copy link
Contributor

@michielbdejong michielbdejong Aug 6, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The summary "Forward an invitation to start sharing" suggests that the agent doing the forwarding (B) is also the agent who starts sharing, but I think it's more accurate to say Alice@A starts sharing.

Also, since B forwards from the inner network to the last mile end-point, "deliver" might have been a better verb than "forward".

The delivery of the notification is not the main functionality exposed by this API endpoint; rather, if and how B notifies Bob is not even the concern of A or of Alice@A. So given that there is also a state change in B, maybe "create" (as in "create an entry in your list of received invites") would have been even better than "forward" or "deliver".

The description "Forwards an invitation received through an out-of-band channel, email for example." describes how the invitation was received, but I think the intention was to describe how the invitation gets forwarded.
So maybe "Forwards a received invitation through an out-of-band channel, email for example." is clearer?

Copy link
Contributor

@michielbdejong michielbdejong Aug 6, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And for the summary I would suggest "Notify the recipient of a new invite"

Copy link
Contributor

@michielbdejong michielbdejong Aug 11, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah wait, I ran through https://reva.link/docs/tutorials/share-tutorial/#4-2-accept-the-token again and this actually looks like accepting the invite is not a server-to-server interaction, but a client-to-server one?
Should the OCM API not only define those, or leave that to each implementer?
In the end it doesn't matter to Alice or to A how Bob and B communicate with each other, right?

post:
summary: Forward an invitation to start sharing
description: Forwards an invitation received through an out-of-band channel, email for example.
parameters:
- name: invite
in: body
description: The JSON object representing an invitation to send to an end-user.
required: true
schema:
$ref: "#/definitions/ForwardInviteBody"
responses:
200:
description: Invitation forwarded.
400:
description: |
Bad request due to invalid parameters, e.g. provider is not valid.
schema:
$ref: "#/definitions/400"
/invites/accept:
post:
summary: Accept an invitation to start sharing.
description: Accepts an invitation so the user on the sender provider's side can initiate the OCM share creation.
parameters:
- name: invite
in: body
description: The JSON object to notify the OCM provider that an invite has been accepted.
required: true
schema:
$ref: "#/definitions/AcceptInviteBody"
responses:
200:
description: Invitation accepted.
400:
description: The invitation token is invalid.
schema:
$ref: "#/definitions/400"
403:
description: Remote service is not trusted to accept invitations.
schema:
$ref: "#/definitions/Error"
definitions:
400:
type: object
Expand Down Expand Up @@ -505,4 +546,42 @@ definitions:
href:
type: string
description: Link to this specific notification.
example: /notifications/9303
example: /notifications/9303
ForwardInviteBody:
type: object
allOf:
- properties:
token:
type: string
description: Token generated by the service sending the invitation.
example: xyz
senderProvider:
type: string
format: url
description: URL of the OCM sender service.
example: https://sender.org
AcceptInviteBody:
type: object
allOf:
- properties:
recipientProvider:
type: string
format: url
description: URL of the receiver OCM service.
example: https://receiver.org
token:
type: string
description: Token received in the invite
example: xyz
userID:
type: string
description: Unique ID to identify the user at the remote provider accepting the invite.
example: 9303
email:
type: string
description: Email ID of the user accepting the invite.
example: [email protected]
name:
type: string
description: Name of the user accepting the invite.
example: Richard Feynman