[tommorris]

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

[randomdrake]

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

[steveklabnik]

Yes, we have. http://en.wikipedia.org/wiki/Web_Application_Description_Lan...

[Geee]

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?

[sopooneo]

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.

[steveklabnik]

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.

[user24]

You could use

OPTIONS /somePath?

[caseysoftware]

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.

[fein]

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.

[thawt]

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.

[steveklabnik]

That's what resources that have form-style affordances offer. See, for example, Collection+JSON.

[ttezel]

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?

[mtts]

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.

[ch]

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

???

[elbear]

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.

[mindcrime]

XML is more human readable than JSON, to my eyes.

[elbear]

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.

[dsego]

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?

[mindcrime]

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

[bpphillips]

This seems similar in goal to the SPORE project (https://github.com/SPORE). Have you seen that and/or considered merging efforts?

[pnathan]

Yes, this sounded an awful lot like SOAP/WSDL.

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