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

51–57 of 57 posts

Re: RAML - RESTful API modeling language

#51

Post by usarid »

viblo wrote: post #44

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.

In short, we wanted an API spec that was much more readable and efficient, showed the structure of the API more clearly, and promoted consistency and reuse. We wanted an API spec that was intuitive enough to just type out in an editor when designing an API. And we iterated on it quite a bit in real-world cases to be really convinced it was worth introducing this different approach.

Re: RAML - RESTful API modeling language

#52

Post by phamilton »

So a lot of people here hate this. I'm not a huge fan, but I want to understand the right way to solve the problem. The problem I see with the APIs I work on is that automated integration tests are hard. I would love a way to answer the questions "Am I sending a request in the right format?" as well as "Am I going to receive data in the form I expect?". If I had a JSON schema or something, I could include those tests in isolation rather than in a big system test environment.

So it sounds like true REST is supposed to solve that. How?

Re: RAML - RESTful API modeling language

#53

Post by tootie »

dragonwriter wrote: post #33
tootie wrote: post #31

Earlier quoted context omitted.

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.

> SOAP is RPC. Yes. > It's fundamentally different. 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 sche…

A schema allows for declarative validation and allows it to be defined once and once per consumer.

Re: RAML - RESTful API modeling language

#54

Post by dragonwriter »

tootie wrote: post #53
dragonwriter wrote: post #33

Earlier quoted context omitted.

> SOAP is RPC. Yes. > It's fundamentally different. 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 sche…

A schema allows for declarative validation and allows it to be defined once and once per consumer.

A well-defined media-type does much the same thing and is what REST is centered on.

An API based on HTTP and schemas rather than media types for content definition/validation is more like SOAP than REST.

OTOH, an API based on resource-oriented hypermedia could incidentally use media types that are defined in terms of schemas, and still be REST.

Re: RAML - RESTful API modeling language

#55

Post by zzen »

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…

Sure, API Blueprint supports JSON Schema. If you're happy to put in the effort, nothing stops you from using JSON Schema in the blueprint and all the tooling built on top of it.

Re: RAML - RESTful API modeling language

#56

Post by auvrw »

zzen wrote: post #55
auvrw wrote: post #43

Earlier quoted context omitted.

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

Sure, API Blueprint supports JSON Schema. If you're happy to put in the effort, nothing stops you from using JSON Schema in the blueprint and all the tooling built on top of it.

but that's my point: there isn't as much library support as there ought be, even for json schema, let alone these newer domain-specific languages that incorperate/extend json schema.

sometimes i think it would make just as much if not sense to define these communication protocols with a bnf grammar (for endpoints and response codes) or to use s-expressions (since json is pretty much just sugared lisp) or some other well-worn-but-adaptable format just because there are already parser generators and scheme interpreters written for every language.

Re: RAML - RESTful API modeling language

#57

Post by usarid »

usarid wrote: post #50
auvrw wrote: post #43

Earlier quoted context omitted.

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

Regarding tooling.. check out the video that just went up on http://raml.org (and on Youtube: http://youtu.be/5o_nExedezw)
Post reply on HN