Hi Jan,
> [..] When I
> >use it, I'm referring to the RESTful Web API an application
> exposes -
> >e.g. I would call the Google Calendar Data API a "REST API".
> I would
> >say every WADL file describes a Web API, and if it follows REST's
> >constraints (is RESTful), a Web API is a REST API.
IMO, the "REST API" term is an abuse of language, a gross but useful
simplification. "RESTful API" would be better as "REST" refers to an
architectural language and "API" to a concrete programming interface. Also,
as REST is a formalization of the architecture of the Web, "Web API" is
synonymous of "RESTful API".
> I consider HTTP to be a REST API and I am having trouble to see
> what a 'Web API' is (in a REST context). From a strict POV,
> all you get
> to do when you do not want to break REST's constraints is to
> make use of HTTP
> and of (standardized media types). All 'API-like semantics'
> have to be dealt with
> in the MIME type (defined as standardizations of state
> transition semantics, e.g. APP's edit-media link rel).
I would not say that HTTP is a REST API, instead that HTTP is a protocol
that was designed based on the REST architecture style principles, and
therefore favors the definition of "RESTful Web APIs" (or "REST APIs" for
short).
> If you have a service that needs exposure of some *DL for the
> client to understand it, you break REST.
I'm not sure I agree. You could view WADL as a programmatic version of HTML,
with hyperlinks and forms. You could break a complete WADL document into
snippets and allow navigation from one snippet to others. Sometimes it is
also useful to aggregate the description of all resources snippets into a
larger one. See how the SiteMap XML description format is important to Web
search engines.
> >So I agree we're not trying to build a REST API. We're trying to
> >produce an API "that makes it easy to build RESTful services",
>
> Maybe I am misunderstanding something, but isn't this
> purely about HTTP? About making it easy to build HTTP-based
> services?
IMO, it as HTTP is favoring the design of RESTful Web Services, we must be
very HTTP-centric, but not unecessary exclude other protocols that could be
mapped to REST/HTTP semantics, like Waka, like a subset of FTP and like HTTP
like protocols like AJP and FastCGI.
> If not, what other REST-architecture besides HTTP do people have
> in mind (IMO it is rather unlikely that we will ever see one :-)[1]
Even if you are correct, I think it is worthwile to exact the higher-level
HTTP semantics into a slighty more abstract model that HTTP headers and
such. Not relying too directly on lower level HTTP syntaxt does help in this
regard.
Our experience with the Restlet API, illustrate that this is both
technically possible and very useful.
Best regards,
Jerome
> [1] Besides WAKA, so there might be a point in staying generic.