search

cs3org / OCM-API

OpenCloudMesh API
38 stars 11 forks source link

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

Closed michielbdejong closed 1 year ago

michielbdejong commented 1 year ago

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 commented 1 year ago

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.