111–120 of 137 posts
I want to give you an idea of how bad things are with REST Api Client . This is a Maven POM for Google APIs for java web project that uses Google APIs for Profile, Drive and Oauth2. Its insane: 4.0.0 com.google google 5 com.google.api.client google-plus-java-webapp-starter war 1.0.0 google-plus-java-webapp-starter Web application example for the Google+ platform using JSON and OAuth 2 https://code.google.com/p/google…
http://static.springsource.org/spring-android/docs/1.0.x/ref...
Earlier quoted context omitted.
Yes my argument is simply that we publish API specs in a machine-readable format to avoid wasting time implementing clients repeatedly. WSDL and WADL had good intentions at heart, but XML is ugly. JSON is nice since it's human-readable and light. Why not publish JSON versions openly for REST APIs, reducing implementation cost for clients?
XML is more human readable than JSON, to my eyes.
Earlier quoted context omitted.
Yes my argument is simply that we publish API specs in a machine-readable format to avoid wasting time implementing clients repeatedly. WSDL and WADL had good intentions at heart, but XML is ugly. JSON is nice since it's human-readable and light. Why not publish JSON versions openly for REST APIs, reducing implementation cost for clients?
> ... my argument is simply that we publish API specs in a machine-readable format ... > ... XML is ugly. JSON is nice since it's human-readable and light. ???
Earlier quoted context omitted.
You could use OPTIONS /somePath?
Thank you for being realistic. REST means more than just GET, POST, PUT, DELETE. Some may make the excuse that call OPTIONS /path isn't straightforward, but I have no clue how you could get more obvious than that.
I really wish there was a DESCRIBE verb that would return a structure of what is expected to be received/sent.
Then microformats could spring up around datatypes returned by DESCRIBE. This is of course very XML.
Edit: This would also allow for automatic discovery of new APIs.
Earlier quoted context omitted.
I agree. The promise of REST APIs is that will be self describing, but for that benefit to be realized, we need general purpose REST clients that can "discover" everything they need to know given just a root uri. Are there any such clients? And no, web browsers do not count.
You could use OPTIONS /somePath?
https://github.com/caseysoftware/web2project-slim
But one of the things I did a little differently is that instead of writing the code and then the docs separately, I pass the validation information from the object itself.. so the API layer doesn't have to know any of it in advance. It can pass that along to the end clients.
I'm not convinced this is the solution but it mostly works for now and would love any & all feedback.
My next proof of concept will be to use Javascript to retrieve the required fields and decorate a simple html form.
All that these sorts of description produce is a low-level API. That can be useful, but what's really needed are high-level APIs that provide meaningful semnatics: my $me = Facebook->new( username => 'autarch' ); $me->post_status("I'm on Hacker News writing this comment"); my $friend = Facebook->new( username => 'imaginary' ); $me->post_on_wall( $friend, "Hey buddy, I am on Hacker News writing this comment" );
Exactly. And this is what clients can provide over generic, one-size-fits-all solutions: fluent, idiomatic, and terse access to APIs.
On the client side, I don't really care (too much) if something is a POST or PUT, I want to send a message or update a repository's metadata or share a photo.
Am I the only one who doesn't like receiving direct orders from article titles?
Writing using authoritative language is very common, and widely considered a best practice. I highly recommend you simply accept it as what it is: the way some people communicate, especially online. It's not worth your time/attention/care to think about this.
I'm curious how this works in practice. What about authorization and parts of the API that are only available to certain users, does the client generator need to be authenticated? Are there standards for describing the meta-data associated with URLs (validation, optional parameters, etc.)?