Capabilities API

[cookeac]

Referenced in #154 and earlier discussions, it would be useful to have a mechanism to determine:

• The collections and events supported by a server
• The methods supported (are these collections GET only or can you POST, or even PUT/PATCH?)
• Whether more complex transactions, which may involve atomic updates to several collections are supported
  And perhaps other things too.

Please submit your suggestions as comments to this issue.

[alamers]

Would providing a specific openapi spec file not do the job? Maybe we could provide a well-known URI for that file and go from there?

[ahokkonen]

As a default for supported methods we could use OPTIONS http method for each endpoints as by specs.

[gra-moore]

Here are a couple of vocabulary based approaches:

https://www.odata.org/blog/introducing-a-capabilities-vocabulary/
https://www.w3.org/1999/11/02-RDFServices/

These approaches look to define a data model for capabilities. They dont have wide adoption that I have seen but could be seen as input to a data model for describing capabilities.

Other options leading on from comments above: Service endpoints could just publish a Open API document that described only the services capabilities they actually had. The nice thing about this approach would be that the complete swagger document could be published as a standard and then implementors just cut away what they are not supporting.

[cookeac]

I think there are different use cases that could be considered for finding out about API capabilities:

• As a developer, what can I do with this particular service? An OpenAPI document sounds ideal.
• My product can talk to many services - how do I know at runtime if a particular API is supported? HTTP OPTIONS would be a method
• My product can talk to many services - at runtime, which filter and sort methods can I expose to users? A vocabulary approach would be helpful.

[cookeac]

No use case for this at present.