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

Stop Writing REST API Clients

ttezel.github.com

Post reply on HN
Print view View original

91–100 of 137 posts

Re: Stop Writing REST API Clients

#91

Post by manishsharan »

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-plus-java-starter

  
    code.google.com
    https://code.google.com/p/google-plus-java-starter/issues
  

  2011

  
    2.0.9
  

  
    
      scm:hg:https://hg.codespot.com/p/google-plus-java-starter/
    
    
      scm:hg:https://hg.codespot.com/p/google-plus-java-starter/
    
    
      https://code.google.com/p/google-plus-java-starter/source/browse/
    
  

  
    
      jennymurphy
      Jennifer Murphy
      Google
      http://www.google.com
      
        owner
        developer
      
      -8
    
  

  
    
    
      google-api-services
      http://mavenrepo.google-api-java-client.googlecode.com/hg
    
    
      google-api-services-drive
      http://google-api-client-libraries.appspot.com/mavenrepo
        
  

  
    
      
        maven-compiler-plugin
        2.3.2
        
          1.6
          1.6
        
      
      
        org.mortbay.jetty
        maven-jetty-plugin
        
          /
          
            
              configurationPath
              ./src/main/resources/config.properties
            
          
        
      
    
    ${project.artifactId}-${project.version}
  
  
    UTF-8
    gfv3ee6
    1.13.1-beta
    1.13.1-beta    
    6.0
  
  
    
      com.google.guava
      guava
      13.0.1
    

 
      com.google.apis
      google-api-services-drive
      v2-rev53-1.13.2-beta
    
  
      
      com.google.apis
      google-api-services-plus
      v1-rev22-1.8.0-beta
      


   
      com.google.api-client
      google-api-client
      1.13.2-beta
    

  
      com.google.api-client
      google-api-client-servlet
      1.13.1-beta
       

    


      

      com.google.oauth-client
      google-oauth-client
      1.13.1-beta
        

    
    	com.google.oauth-client
    	google-oauth-client-servlet
    	1.13.1-beta
    


    
    	com.google.http-client
    	google-http-client-gson
    	1.13.1-beta
    

    
    	com.google.code.gson
    	gson
    	2.1
    

  
     com.google.http-client
     google-http-client
     1.13.1-beta
   

  
    
      com.google.http-client
      google-http-client-jackson2
      1.13.1-beta
    

  
        javax
        javaee-web-api
        ${webapi.version}
        provided
        
    
      org.apache.commons
      commons-lang3
      3.0.1
    

  
	commons-logging
	commons-logging
	1.1.1
  

 
	org.apache.httpcomponents
	httpclient
	4.0.3
  

  
	org.apache.httpcomponents
	httpcore
	4.0.1
  


  
	org.codehaus.jackson
	jackson-core-asl
	1.9.4
  

  
	javax.jdo
	jdo2-api
	2.3-eb
  

  
	com.google.code.findbugs
	jsr305
	1.3.9
  

  
	com.google.protobuf
	protobuf-java
	2.2.0
  

  
	javax.transaction
	jta
	1.1
  

  
	xpp3
	xpp3
	1.1.4c

Re: Stop Writing REST API Clients

#93

Post by unclebucknasty »

There is a lot of talk about this idea being SOAP-like, but I disagree.

SOAP was insane and its counterpart, WSDL (which is really the part that is most comparable to this idea), was even more insane.

But, the basic premise was not bad. It was the execution which sucked by trying to account for every situation, adding namespaces, etc. And if you ever worked with language libs designed to interface with SOAP/WSDL, it would make you slap a bunny.

With this idea, however, adding an optional JSON-based descriptor language could be helpful. Key would be to keep it simple, allowing the bare mnimum number of data types, with one simple array structure for collections. Allow object definitions with an infinite number of nesting levels, and that would be it. I wouldn't even get into optional vs required stuff, validation, etc. That stuff should stay at the application level. Why stuff it into the interface layer?

From there, it would be easy to develop libraries to generate clients in any language for any API just by feeding it the JSON descriptor. Or (as I think the author intended) just use one universal client that any app can use. For languages that aren't strongly typed anyway, the latter would be fine.

Someone mentioned that it would require the server side devs to keep the descriptor in sync with the code. No biggie for apps that already offer client libs in different languages and must keep them up to date anyway. Not to mention there should be some doc that needs to be kept in sync (REST is not typically self documenting in reality).

In any event it wouldn't be required. What would be the harm in creating a standard for those apps that choose to use it?

Re: Stop Writing REST API Clients

#94

Post by fein »

user24 wrote: post #74
sopooneo wrote: post #66

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?

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.

Re: Stop Writing REST API Clients

#95

Post by robbles »

michaelw wrote: post #14

Sigh. This is optimizing for the wrong problem. Stop creating REST APIs that are only level 1 or 2 (see http://martinfowler.com/articles/richardsonMaturityModel.htm... ). Start writing HATEOS systems where the client is coupled to the semantic rather than the syntax. Machine parseable interface descriptions might get rid of some boilerplate but it doesn't make for a more robust client-server relationship.

Can you give an example of an acceptable implementation of a HATEOAS REST API (wow, that's a lot of letters) with an associated client that actually uses it?

My experience has been that you can't communicate much through HATEOAS that's actually beneficial to a human programmer writing a client. Sure, you can add all the hypermedia links you want in your API responses, but how does that make writing a client easier? Wouldn't it just be helpful to crawlers?

Not trying to put down the idea - I want to believe, but I just haven't seen any obvious examples using it in the real world yet.

Re: Stop Writing REST API Clients

#96

Post by steveklabnik »

stephen wrote: post #86
ms123 wrote: post #11

Hypermedia APIs are an approach to solve this problem. It essentially does what you did, and add some other benefits like de-coupling URIs.

Really? Seems to me like Hypermedia APIs should move the problem from the wire protocol to the application protocol? Hypermedia says "oh yeah, here's some markup, look there are URIs in it". For a human user, we're like "cool, I'll try and click these, see what they do". But software is going to want "um...okay, how to I parse this markup, and how do I generate the submissions you want? And, okay, you can change URIs…

You're forgetting form-style affordance. For example, if you were using HTML as your media type, the equivalent of the first example would be
> AFAIK you're still going to want some marshaling to/from host language.

Actually, you explicitly _don't_ want this. That's what hypermedia APIs are trying to remove.

Re: Stop Writing REST API Clients

#97

Post by pfarrell »

petercooper wrote: post #18

We could give a name to the language we use to define such files. It's a language that defines Web services, so perhaps Web Services Description Language? :-) http://en.wikipedia.org/wiki/Web_Services_Description_Langua... Flippancy aside, maybe there's a need for a next generation of this that skips all the XML headaches after all.

There are no new problems, only new engineers.

I have been puzzling over this API discovery issue on my current project (building out a reporting API).

I'm starting with self documentation for developers built in, not this (admittedly admirable) goal of a machine generated API mapping layer. I think the main issue is, you're trying to generate a generic interface to something that isn't, itself, generic.

How many versions of "RESTful" have you encountered?

Building a generic interface to non-generic interfaces is the domain of software engineers. Until we have machines building both sides of this equation, there will always be a need for human intervention.

Re: Stop Writing REST API Clients

#98

Post by pfarrell »

manishsharan wrote: post #91

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…

What would you remove? How could it be simpler? I don't mean how could it be less verbose, but how could you describe those various project attributes in a way that wouldn't lead you to another markup language with the same data?

Re: Stop Writing REST API Clients

#100

Post by rdtsc »

mixedbit wrote: post #63

This article is not at all about REST, it is about RPC and its shortcomings. These shortcoming were fixed by REST, and the author of the article rediscovers these fixes. A key features of a REST API is that is self describable, in a sense, that it has a single entry point from which a generic client can automatically discover available resources and actions. APIs in the given examples are not like this, they require…

> A key features of a REST API is that is self describable

How practical is that, in reality?

I know I've added the whole HATEOAS thing to my API and I am not sure if it just makes my IDs longer. Customers seem to hard-code the API entry points anyway. Everyone of course says "Oh, yeah this is cool" but when it comes to doing it given performance constraints, they don't want to start generating 10s of extra GET requests on startup to rediscover the API.

Now I can say "well not my problem" and that is what I say, except that looking back and I just don't see the practice match with the supposed theoretical advantages of the REST-ful interface.

Another issue I see happening, is the return of message bus like interface brought about by Websockets and server push optimizations it makes possible. I think REST and Websocket's channels/message bus architectures will have a battle at some point -- and one will end up dominating.

Just like AMQP is becoming a standard for message brokers, I think at some point that will be extended to the browser. Kind of like RabbitMQ has the web-STOMP plugins. I can see future hotness being just that -- message broker architecture all the way to the web client and everyone will laugh at REST-ful hype just like we are laughing at SOAP now.

Post reply on HN