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

31–40 of 57 posts

Re: RAML - RESTful API modeling language

#31

Post by tootie »

dragonwriter wrote: post #30
tootie wrote: post #28

Earlier quoted context omitted.

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

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.

Re: RAML - RESTful API modeling language

#32

Post by taeric »

arethuza wrote: post #16
taeric wrote: post #10

Is there any reason to think that this will be better than wsdl style descriptions? To wit, WADL tried this, but it seems to have stalled heavily. I should add I do not find WSDL/WADL as horrible as it could be. There is something nice about being able to generate a client in one of any given number of languages that can hit a service. Sorta sucks when you can't do that with a traditional workflow in REST.

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

Oh, no doubt that there were terribly done WSDL mechanisms out there. Probably most of them. However, many of the mature choices now have a fairly reliable "generate a client off of this wsdl" to get a generic api you can hit from your language of choice. I recall using python and such was actually mostly as expected.

Compared with most "RESTful" services, which require me personally figuring out everything and home growing every portion. Heaven help you if someone makes a change breaking something you had already done.

Re: RAML - RESTful API modeling language

#33

Post by dragonwriter »

tootie wrote: post #31
dragonwriter wrote: post #30

Earlier quoted context omitted.

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

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

Re: RAML - RESTful API modeling language

#34

Post by tootie »

arethuza wrote: post #16
taeric wrote: post #10

Is there any reason to think that this will be better than wsdl style descriptions? To wit, WADL tried this, but it seems to have stalled heavily. I should add I do not find WSDL/WADL as horrible as it could be. There is something nice about being able to generate a client in one of any given number of languages that can hit a service. Sorta sucks when you can't do that with a traditional workflow in REST.

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

If you want strongly-typed RPC integration with generated clients then something like Thrift, protobuf or Avro are vastly superior. Very simple and lightweight.

Re: RAML - RESTful API modeling language

#35

Post by mcguire »

First, this seems to view the URLs as primary. They aren't. The document formats are the most important part, even if you are doing a http-rpc style, not-really-REST interface.

Second, YAML? Haven't we already learned that markup languages don't make good programming languages? (That's what this is, right? Nobody is really going to use it to document an API, any more than anyone uses WSDL for more than generating stubs.)

Third (and not really germane), JSON schemas? Describing the format of JSON documents, in JSON? Because XML schemas are so wonderful?

Re: RAML - RESTful API modeling language

#36

Post by riffraff »

arethuza wrote: post #16
taeric wrote: post #10

Is there any reason to think that this will be better than wsdl style descriptions? To wit, WADL tried this, but it seems to have stalled heavily. I should add I do not find WSDL/WADL as horrible as it could be. There is something nice about being able to generate a client in one of any given number of languages that can hit a service. Sorta sucks when you can't do that with a traditional workflow in REST.

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?

Re: RAML - RESTful API modeling language

#37

Post by crazychrome »

i'd say it's a wrong direction, or at least a premature optimization. it smells like WSDL/SOAP, UML and other attempts to create a layer of abstraction which is too high level to be useful while not insightful enough for conceptualization, and too prescriptive to be practical.

how about further narrow down the scope, e.g. only focus on describe relationship among apis (how a song api related to album, musician apis)?

Re: RAML - RESTful API modeling language

#38

Post by jamespitts »

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.

Totally agree on both points...

There's nothing like creating within a clear, clutter-free space. This is what partly drives the enthusiasm when some new hotness hits the dev scene. Other drivers include liberation from gatekeepers and previous decisions.

The possibilities seem endless and it encourages creativity, even if you have to do some nasty bootstrapping to get there.

Re: RAML - RESTful API modeling language

#39

Post by jjsz »

inerte wrote: post #27
mishkinf wrote: post #26

https://github.com/mishkinf/apiknow is another project to help build out an api documentation and Test Drive it

I think Swagger [1,2] is similar, which I am currently using, via node/restify. Awesome little project that generates docs and an interface for API consumers to experiment with. 1 - https://developers.helloreverb.com/swagger/ 2 - http://swagger.wordnik.com/

How does Swagger compare with Scrooge (Twitter's Scala / Apache Thrift code generator)[0]?

[0] http://twitter.github.io/scrooge/

Re: RAML - RESTful API modeling language

#40

Post by jalfresi »

tootie wrote: post #34
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.…

If you want strongly-typed RPC integration with generated clients then something like Thrift, protobuf or Avro are vastly superior. Very simple and lightweight.

Totally agree, these all fit the bill far better and with far less opacity than SOAP and it's ilk.
Post reply on HN