Draft text to rewrite this API doc to more of a protocol spec

[michielbdejong]

No description provided.

[michielbdejong]

I was thinking this document could be more valuable if we add some more text around the different steps sender and receiver go through.

By using "MAY" instead of "SHOULD" in the right places, I think this is possible without adding more requirements or bringing things into scope that are currently out of scope.

For instance, we can document /ocm-provider and describe how it is used in practice in some real-world interactions (even in an interoperable way across implementations!), but without making it a requirement. For instance when sharing only from and to the ScienceMesh, this endpoint is not needed.

Another example are the notificationType strings that are used interoperably across some (but not all) implementations in practice; we can at least describe the prevalent notificationType strings as things a server "MAY" support, so we don't end up with an eco-system where the same notification type is identified with more than one string.

[glpatcern]

Hello Michiel, I think we should also resume this in view of v1.1. I have contributed the invite workflow and amended a couple of things also given that the discovery endpoint is officially in the spec. What do you think?

[glpatcern]

I have incorporated the invite description so it's easier to read through. For the rest, I leave it to you to have a look / improve.

[glpatcern]

I suggest to move on with all this, as discussed we can always improve and the added text already documents several undocumented aspects. I will also build on top of this to document the webdav access in OCM v1.0, as discussed in #70.