Closed smrgeoinfo closed 4 years ago
I think it is clear that a WebAPI
type in discovery terms relates to an instance of the API, whereas the documentation linked to would relate to the contract of that API.
Lets see if there are any other opinions on this...
@smrgeoinfo if helpful at OpenActive we define both specifications (in their true sense) and machine readable documentation, and expect them to be referenced by our implementers using WebAPI
as specified:
"conformsTo": "https://openactive.io/open-booking-api/EditorsDraft/",
"documentation": "https://developer.openactive.io/open-booking-api",
"endpointDescription": "https://openactive.io/open-booking-api/EditorsDraft/swagger.json",
WebAPI
aids discovery of a service instance, rather than describing that service instance in any formal sense. WebAPI
is also not intended to aid discovery of a specification (though, as above, can link to one). Indeed the definition is currently "An application programming interface accessible over Web/Internet technologies".
Agree that conformsTo
, as in my small example above, is where you'd reference a formal spec.
Distinguish description of a WebAPI as a specification from an instance of the WebAPI accessible at some endpoint. See ongoing DCAT discussion about endpoint vs DataService. Does WebAPI describe a service instance, or the service specification. A service instance has a particular endpoint, some particular implementation (that should be invisible and irrelevant to the service user), and possibly some particular coupled data. A WebAPI specification specifies:
The API specification does not necessarily specify any particular endpoint or data. The intention of an interface is that it can be implemented many times, how it is implemented should not matter; in this case the service specification is a a property of an endpoint.
In many cases the API is only implemented one time, in which case there is only one endpoint, and the specification applies in that case to that endpoint, so the concepts are conflated. The conformsTo property could be used to link the endpoint to the service specification.
An endpoint agnostic API specification would have potentialAction target/EntryPoints that have urlTemplates using paths that are relative to a 'baseURL' variable. In this case the 'endpointURL' for a service instance would be used as the 'baseURL' for constructing requests for the potentialActions.