51–59 of 59 posts
Earlier quoted context omitted.
How does this miss the point of REST?
> How does this miss the point of REST? Because if it didn't, the full API description language would be: api-root: Or, for a pedantically detailed version: api-root: media-types: - -
Earlier quoted context omitted.
> How does this miss the point of REST? Because if it didn't, the full API description language would be: api-root: Or, for a pedantically detailed version: api-root: media-types: - -
Are there any extant REST API's for which one could programmatically generate a client library based purely upon the root URL and media types?
For a truly RESTful API, the question you ask is somewhat incoherent. A client for a RESTful API consists of two key sets of components: functionality for sending and receiving resource representations to and from locations identified by URIs, and functionality for handling resource representations of particular media types. Assuming you have those, you don't need to "programmatically generate a client library" with the particular base URL of a particular API root, you access a URL that provides resources of any of the supported media types and your off to the races without programmatically generating anything.
Is this possible in practice for real implementations of RESTful principles? Yes, including the one that motivated the articulation of the REST principles, the WWW.
Is REST appropriate for all APIs? Maybe, maybe not. But its probably not useful to anyone to just call every web service that uses HTTP and isn't SOAP "RESTful".
Earlier quoted context omitted.
It describes how to construct URLs to get from one state to another (e.g. from a base URL to a list of songs, or from the list to an individual song). REST URLs are supposed to be opaque. A RESTful resource should provide links to its related resources for the user agent to navigate. There's nothing wrong with what the author is trying to do, but it's nothing to do with REST.
Oops. That's one detail I missed in all those API tutorials. Thanks.
Earlier quoted context omitted.
How does this miss the point of REST?
> How does this miss the point of REST? Because if it didn't, the full API description language would be: api-root: Or, for a pedantically detailed version: api-root: media-types: - -
while actually allowing you to build RESTful APIs
The APIs modeled by this language are not RESTful: in fact, the use of this type of WSDL-like description is the antithesis of the hypertext-centric core concept of REST. Calling this a "RESTful API modeling language" is like calling a water cannon a flamethrower. If we're going to call this RESTful, we might as well call SOAP RESTful.
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
> A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
The need for a document like this in the first place demonstrates that the API is not REST. These systems are simply ad hoc, partially specified RPC systems operating over HTTP.
I've almost given up caring about what REST means due to endless debates and misunderstandings about this. REST just means any HTTP-based API where operations and inputs/outputs are modeled with HTTP fields these days.
Very cool, it feels like WSDL for REST EDIT: spelling
True REST shouldn't require a WSDL-like interface. The semantics of the graph it describes should be enough. This model, however, has yet to be fully realised; largely because of the large upfront cost in R&D. At my work, we are trying to develop in this area, but it's slow going.
It might be nice if this was described in an existing data format (YAML, anyone) as a particular form of structure, rather than inventing a new data format.
What do you think about API Blueprint [1]? It is based on Markdown. [1]: https://apiblueprint.org
YAML strikes a nice balance between machines and people, but I wouldn't want to write a blog post in it.
Markdown is great for blog posts, but APIs are terse.
It might be nice if this was described in an existing data format (YAML, anyone) as a particular form of structure, rather than inventing a new data format.
RAML is essentially a YAML with a specific schema. Tell your IDE to treat .raml files as .yaml and all the syntax highlighting, etc will work perfect
It appeared to have weirdness from the homepage:
- secured: !include http://remote-host/secured.ymlWhich is invalid YAML.
It turns out this is probably an unfortunate word-wrap in the page, where a non-wrapping text field would better convey the format.