Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

RAML - RESTful API modeling language

raml.org

Post reply on HN
Print view View original

41–50 of 57 posts

Re: RAML - RESTful API modeling language

#41

Post by arethuza »

riffraff wrote: post #36
arethuza wrote: post #16

Earlier quoted context omitted.

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

in what ways did you find corba/idl more limited than soap/wsdl?

Not so much that Corba/IDL were intrinsically more limited than SOAP/WSDl - more that they were less tightly integrated with development environment and platforms so generally, in my experience, seemed to be used with a bit more care.

Re: RAML - RESTful API modeling language

#42

Post by be-prepared »

zzen wrote: post #25
jamespitts wrote: post #24

Standards like this enable new value, but make it harder for newcomers. Worse, they add a lot of burdensome work in situations where implementation or compliance is demanded of developers. Complexity-enabling standards are often a sign that a funky, little nook of software is maturing. It is a sign of huge success, too, because new layers are beckoning to lay on top of an old layer. We had a good run with REST and JS…

Personally, I believe there is a way to enable new value while fighting back the complexity and corporate engineering culture. REST needs to mature and get tooling. But we need to avoid the WSDL complexity.

Good luck avoiding complexity when you hit P2P security, transactions, etc.

Re: RAML - RESTful API modeling language

#43

Post by auvrw »

zzen wrote: post #20

(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 use…

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

the (open source) tooling is what makes or breaks adoption of languages like these, and neither of them has much to offer in that regard. apiblueprint has code for node and .net, raml doesn't even list libraries that can parse it. contrast that with json schema: there's an rfc standard and libs that handle validation in almost every widely-used general-purpose language...

... and that's just the bare minimum of tooling i would hope for from a popular standard. i'd be much more psyched to find an equivalent library of " rel="nofollow">http://www.rexx.com/~dkuhlman/generateDS.html> for jsonschema than i am to see yet another domain specific language with bad/no tooling. a standard without an implementation is nothing more than a suggestion -- and one that is unlikely to be strictly adhered to.

Re: RAML - RESTful API modeling language

#44

Post by viblo »

It would be interesting to hear some reasoning from the RAML people about what it brings compared to existing solutions like Swagger. From a quick look it seems like they solve the same thing except that RAML use yaml and is much more immature.

Re: RAML - RESTful API modeling language

#47

Post by usarid »

Terretta wrote: post #21

When looking at the concept, it's interesting to me how much the pseudo code looks like a real REST API handler written in a state machine DSL. Decision graph: http://clojure-liberator.github.io/liberator/tutorial/decisi... Actual code: http://clojure-liberator.github.io/liberator/tutorial/all-to... Progenitor = Erlang Webmachine: https://github.com/basho/webmachine/wiki/Overview I'd rather write a working API than t…

I like to think design-first and if possible in the most minimal fashion that captures the interface, but I certainly see (and share) the appeal of writing working code. In many cases like that (including APIs that are already implemented in code), generating a clean RAML spec from the code is a good way of capturing the interface itself, in a very readable way that shows the structure. Thanks for these links -- very interesting!

Re: RAML - RESTful API modeling language

#48

Post by meowface »

nfoz wrote: post #45

Really? Dark gray until mouse hover makes different paragraphs glow ??? web devs, whyyyyy

I can understand the intent: showing exactly which parts of the document match up with the section descriptions. That itself is not a bad idea.

But making all of it dark gray (so, intended to be not-visible) by default is really silly.

Re: RAML - RESTful API modeling language

#49

Post by usarid »

zzen wrote: post #20

(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 use…

(disclaimer, I'm from the RAML workgroup -- nice to see you here, Jakub!)

As you know, we carefully considered swagger and blueprint, before embarking on the RAML path. There's a bunch of us who are strong believers in very human-readable API specs, though we also strongly believe in clean API specs that reveal the structure of the API and encourage consistency and reuse -- and we just didn't find that in existing DSLs.

We're actually not finding any issues embedding markdown documentation in RAML at just those points in the spec that need documentation, while letting the spec itself do the talking when more documentation would just be repetitive. That way the structure of the API is manifest.

We also find the spec to be much DRYer in RAML than other ways; less repetitive reading means quicker and better grokking of the API.

I think the point about syntax highlighting in generic editors is debatable, but that's fine -- as you say, we have two different approaches and we'll keep each other on our toes, to the benefit of the community. Apiary's dedication to user experience is an inspiration to us. And just in case, my invitation to you to consider collaborating with us and the other workgroup members on RAML remains very much open.

Re: RAML - RESTful API modeling language

#50

Post by usarid »

auvrw wrote: post #43
zzen wrote: post #20

(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 use…

> 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. the (open source) tooling is what makes or breaks adoption of languages like these, and neither of them has much to offer in that regard. apiblueprint has code for node and .net, raml doesn't even list libraries that can parse it. contrast that with json schema: there's an rfc s…

couldn't agree more that it ain't much without tooling -- RAML's been out for only about 24 hours, but open-source tooling is right around the corner (weeks, not months).
Post reply on HN