News for hackers. Stuff that matters.
Re:Stop Writing REST API Clients by tommorris on Sunday February 24, 2013 @10:56AM (#5274609)
Substitute "XML" for "JSON" and we've now come full circle.

The point about REST is that it is self-describing. And ideally should be using the same URIs as the version people clicking around in Firefox or Chrome see. The API is just the XML or JSON or whatever is flavour of the week version of the HTML version.

(Or we could use embedded data—microformats, microdata, RDFa—and get rid of that distinction.)

Re:Stop Writing REST API Clients by randomdrake on Sunday February 24, 2013 @11:48AM (#5274836)
Agreed. I came here to post something similar but I was going to mention working with SOAP[1] in addition to what you mentioned. It sounds like the OP is trying to do something which sounded very much like using SOAP and XML to me.

To paraphrase the OP, "Since so many APIs can be described in similar terms, why don't we have some sort of standard that one can look at to identify how to use the API instead of letting the API speak for itself?"

When you start going down this track, you're not only making things complicated on the client's end of things. On the server side, you're having to maintain two things for the API now. First: the ruleset, ensuring it's 100% to spec lest a client fail. Second: the code generating the response in the first place.

I've built clients and servers for both RESTful and SOAPy APIs and I can say I would take REST any day.

[1] - http://en.wikipedia.org/wiki/SOAP

Re:Stop Writing REST API Clients by steveklabnik on Sunday February 24, 2013 @11:54AM (#5274853)
Re:Stop Writing REST API Clients by Geee on Sunday February 24, 2013 @11:48AM (#5274832)
I don't think there is a well-known way to self-describe available and required parameters nor any other validation requirements, or am I wrong?
Re:Stop Writing REST API Clients by sopooneo on Sunday February 24, 2013 @12:07PM (#5274905)
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.
Re:Stop Writing REST API Clients by steveklabnik on Sunday February 24, 2013 @12:22PM (#5274979)
A YC company has a hypermedia-ish API: https://www.balancedpayments.com/docs/api?language=bash

You can see links to the clients on the right.

Re:Stop Writing REST API Clients by user24 on Sunday February 24, 2013 @12:54PM (#5275120)
You could use

OPTIONS /somePath?

Re:Stop Writing REST API Clients by caseysoftware on Sunday February 24, 2013 @04:45PM (#5276041)
I built out a proof of concept on top of my open source project:

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.

Re:Stop Writing REST API Clients by fein on Sunday February 24, 2013 @02:37PM (#5275561)
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 by thawt on Sunday February 24, 2013 @04:39PM (#5276027)
The problem with OPTIONS is it doesn't describe anything about the data the resource returns.

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.

Re:Stop Writing REST API Clients by steveklabnik on Sunday February 24, 2013 @09:10PM (#5276916)
That's what resources that have form-style affordances offer. See, for example, Collection+JSON.
Re:Stop Writing REST API Clients by ttezel on Sunday February 24, 2013 @12:02PM (#5274889)
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?
Re:Stop Writing REST API Clients by mtts on Sunday February 24, 2013 @01:20PM (#5275228)
XML is human readable. It was meant to be (this is why it's text instead of some binary format). It's just really, really verbose, which is what this JSON spec is going to end up being once it's dealt with all imaginable edge cases.
Re:Stop Writing REST API Clients by ch on Sunday February 24, 2013 @12:53PM (#5275106)
> ... 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.

???

Re:Stop Writing REST API Clients by elbear on Sunday February 24, 2013 @04:38PM (#5276024)
Yes, there are some dots you need to connect between his two statements. I'm assuming that he meant the following: those machine-readable specs also need to be read by humans at some point, just like code, and, since JSON is more readable, he proposes using it instead of XML.
Re:Stop Writing REST API Clients by mindcrime on Sunday February 24, 2013 @02:08PM (#5275431)
XML is more human readable than JSON, to my eyes.
Re:Stop Writing REST API Clients by elbear on Sunday February 24, 2013 @04:33PM (#5276010)
That may be so, but most opinions I hear in discussions about XML vs JSON say that JSON is more readable, probably because it's less redundant and similar to data structures found in some programming languages.
Re:Stop Writing REST API Clients by dsego on Sunday February 24, 2013 @03:51PM (#5275849)
Really? Let's write a shopping list on a piece of paper in JSON and XML. Which one would be more similar to the way we write down lists in real life?
Re:Stop Writing REST API Clients by mindcrime on Tuesday February 26, 2013 @12:32AM (#5284169)
Really? Let's write a shopping list on a piece of paper in JSON and XML. Which one would be more similar to the way we write down lists in real life?

XML:

   <list>
    <items> 
       <item>Milk</item>
       <item>Eggs</item>
       <item>Bread</item>
       <item>Butter</item>
     </items>
   </list>

JSON:

    {
       "list": {
         "items": [
            "Milk",
            "Eggs",
            "Bread",
            "Butter"
        ]
      }
    }

I don't know that either one is particularly close to the way I'd write down a list in real life, to be honest. This is a pretty trivial sample, and neither is especially hard to read/parse by a human. But the JSON still looks closer to line-noise to me. :-)
Re:Stop Writing REST API Clients by bpphillips on Monday February 25, 2013 @10:53AM (#5279504)
This seems similar in goal to the SPORE project (https://github.com/SPORE). Have you seen that and/or considered merging efforts?
Re:Stop Writing REST API Clients by pnathan on Sunday February 24, 2013 @12:35PM (#5275034)
Yes, this sounded an awful lot like SOAP/WSDL.

Hmmmm. Maybe JSON should just take pages from their book instead of reinventing the wheel?