RAML - RESTful API modeling language

Or how about an angular service that parses a raml file and returns a resource that implements up all models and methods ?

No need to stub it, just generate it on the fly.

Server side too. At least for quickly iterating and hand implement only the methods that require special handling.

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!)

Personally I think WSDL is an eldritch abomination that I utterly loath - for the sake of "generating a client" you can end up with a opaque mess that can be very difficult to diagnose problems with - particularly when different technology platforms are used on the client and server.

I never thought I'd say this, but I actually had fewer problems with CORBA and ONC RPC based systems than SOAP/WSDL based web services. Probably because they were so limiting that the interfaces tended to be quite straightforward - rather than the baroque approach often favoured by "enterprise" web services.

I will happily sacrifice a bit of development time for something that is much easier to troubleshoot - give me RESTful web services any day.

> I thought the whole point of REST is that it is discoverable at runtime.

Yes. This is about the kind of pseudo-REST that is sometimes called RESTful and has nothing to do with REST as it iis just a plain HTTP-based API.

(disclaimer, I'm founder of Apiary, which started apiblueprint.org)

I'm happy that Mulesoft are getting on the "better, human readable API DSL" bandwagon. It's very important.

At Apiary we found that embedding one format (Markdown, for human-readable documentation) into another format (YAML, for structured parseable data) is hard for the consumer, tough for the text editors/IDEs/syntax highlighters and ultimately useless. That's why apiblueprint.org is PURE markdown, that displays well on GitHub, has great syntax-highlighting support in your editor - and is just as parseable (since we ship an MIT-licensed parser with it).

I wish we could've united on a single format, but I guess the stronger will win and a little competition is always good for the end-users.