I dont understand what the purpose of this is. I thought the whole point of REST is that it is discoverable at runtime. If you have an "API Spec" doesnt that mean the server owner is now beholden to that spec; that changes to their resources would break compatability with any client written to conform to the spec?
I thought everything you needed to write a REST API client is included in the media-type specification and the rel profile?
For example, the spec for the HTML media-type details that link elements with the rel type of "stylesheet" should be resolved by HTTP GET.
My understanding was that (in the example given) you write a spec for your music description media-type e.g. MUSICML, and register it with IANA (because media-types MUST be registered with a central authority). Then your client only need make a HTTP OPTIONS request to see that the Content-Type e.g. vnd.example.com/musicml+v1.0 and the methods allowed on that resource.
As long at the client uses the described rel profiles appropriate to the media-type MUSICML e.g. the spec specifies that the rel type "play" should HTTP GET the specified WAV file and play it in the client, then the server owner is free to modify the API endpoints as they wish.
I never understood why people insist in adding more layers of cruft on top of a perfectly adequate transfer protocol (HTTP) that is almost always worse and brittle than what the existing protocol already provides.
(don't get me wrong, I appreciate that hardly anyone does rest properly, but that doesnt mean WSDL-flavour-of-the-month will have as much uptake as HTTP itself!)
I think the different definitions for REST have really muddied the water. To the REST purist, RAML is falling well short of being truly RESTful for reasons which you've mentioned. In other words, RAML isn't REST at all. To most others, REST is simply another RPC, like SOAP (hence all of the comments saying this is not much better than SOAP). Those of the latter thinking need someway to describe how their API should be consumed other than hypermedia types, so specs like RAML are born.
On their site, they say, "RAML isn't strict: in the end it is only describing HTTP with a few higher-level (optional) constructs." Looks like it's aiming to describe HTTP and URLs rather than hypermedia types.
Yeah, and I see that approach mostly failing. The notion of resource-orientation and HTTP verbs is really useful, but being true to Fielding's dream is not a priority for most organizations. Stronger typing and explicit descriptors are really useful in an enterprise environment.
If we want a non-RESTful (in the strict sense) solution with those particular enterprise features, we have SOAP+WSDL.
Reinventing the wheel and calling it RESTful is non-helpful (because, again, we have a mature infrastructure of tools filling that need in the SOAP+WSDL space, so if we don't need a new approach, it would be more efficient to use them rather than rebuild them, and if we do need a new approach, well, reinventing SOAP isn't it.)
REST does offer solutions to those problems, but these pseudo-REST approaches drop exactly the pieces that address those concerns and replace them with approaches based on the way earlier, pre-REST, systems approached the problem. Which amounts to throwing out the core of REST for no gain over just using the earlier technologies.
SOAP is RPC. It's fundamentally different. REST is not completely undone just because you want validation. Without a schema or DDL, you're still validating but you're doing it in code.
It's fundamentally different than REST, sure. Its not fundamentally different than "REST" that abandons resource-oriented hypermedia.
> REST is not completely undone just because you want validation.
REST includes a validation model (indeed, its centered around one.)
It is completely undone when you toss that out and replace it with a different one.
> Without a schema or DDL, you're still validating but you're doing it in code.
With a schema or DDL, you are validating in code. It may be code in an external library or tool, but that's just a possibility with any validation model, whether its Schema-based, or Media-type-based (as in REST), or based on something else.
I thought everything you needed to write a REST API client is included in the media-type specification and the rel profile?
For example, the spec for the HTML media-type details that link elements with the rel type of "stylesheet" should be resolved by HTTP GET.
My understanding was that (in the example given) you write a spec for your music description media-type e.g. MUSICML, and register it with IANA (because media-types MUST be registered with a central authority). Then your client only need make a HTTP OPTIONS request to see that the Content-Type e.g. vnd.example.com/musicml+v1.0 and the methods allowed on that resource.
As long at the client uses the described rel profiles appropriate to the media-type MUSICML e.g. the spec specifies that the rel type "play" should HTTP GET the specified WAV file and play it in the client, then the server owner is free to modify the API endpoints as they wish.
I never understood why people insist in adding more layers of cruft on top of a perfectly adequate transfer protocol (HTTP) that is almost always worse and brittle than what the existing protocol already provides.
(don't get me wrong, I appreciate that hardly anyone does rest properly, but that doesnt mean WSDL-flavour-of-the-month will have as much uptake as HTTP itself!)