search

webapi-discovery / rfcs

w3c WebAPI Discovery Community Group - Request For Comments
https://webapi-discovery.github.io/rfcs
The Unlicense
4 stars 1 forks source link

API specification vs. endpoint #13

Closed smrgeoinfo closed 4 years ago

smrgeoinfo commented 4 years ago

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:

  1. the protocol for communicating (transport and request syntax)
  2. information model for the content of requests and responses
  3. the serialization scheme(s) for the data in service requests and responses (xml, xml schema, JSON, JSON schema, rdf, rdf vocabulary).
  4. the resources and operations on those resources that the service offers.

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.

MikeRalphson commented 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.

smrgeoinfo commented 4 years ago

Lets see if there are any other opinions on this...

nickevansuk commented 4 years ago

@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.