Hacker News Reader

Hacker News

Comment by masklinn | Hacker News Reader

Full thread

masklinn

> Quotes API Returns latest quote(s) for a given currency pair.

> Ticker:

> URI: GET https://www.bitcoinica.com/api/quotes/[currency_pair].json

That's RPC over HTTP, not a RESTful API.

edit: well, apparently HN sides with meaningless keyword-babble, great.

View on HN

The request is not transmitted in JSON. So it's not JSON-RPC at least.

http://en.wikipedia.org/wiki/Representational_state_transfer...

- The URI is RESTful. (Explicit collection and member actions, with common namespace.)

- Supports both JSON and XML. (Internet media types)

- Bitcoinica API utilizes three of the four RESTful Web Services methods - GET, POST and DELETE. (HTTP methods)

But I'm not sure about the hypertext part, because I don't understand what hypertext means here. Is Bitcoinica's interface considered hypertext-driven?

The concept of 'RESTful URIs' is common, but it doesn't appear in the original dissertation, and it doesn't make much sense; because of HATEOAS¹, you shouldn't ever need to know what the URIs are.

> I'm not sure about the hypertext part, because I don't understand what hypertext means here. Is Bitcoinica's interface considered hypertext-driven?

It means that the docs should only have to document a single URI (the entrypoint) and the formats, which should have links to the various parts of the API.

For example, you could have an URI, say 'bitcoinica.com/api'. Then you GET that, and it returns a JSON file with the following key/value:

     "ticker": "http://bitcoinica.com/api/ticker"

Now the client knows how to get to the Ticker. Then you GET that, and you receive a new list:

    { "btc-dlr" : "http://.../api/ticker/btc-dlr", "btc-eur": "http://.../apu/ticker/btc-eur", ...

Now the client knows how to request a certain currency pair.

This means the URLs can change without breaking all the existing clients.

In general, I'd say this is "kind-of" RESTful. It doesn't follow HATEOAS and it uses custom formats² (it's inevitable, since there's no standard for this). Having URLs for each concept and reusing HTTP methods and auth is RESTful, though.

¹ Hypermedia as the Engine of Application State ² JSON and XML aren't really formats, they're more like transport mechanisms. Formats are KML, MathML, atom, etc. The point is that knowing it's XML or JSON tells you nothing, your clients are still completely tied to their API. It's just nice not having to write a parser, but it's not a standard format.

I understand the appeal of using json, but it doesn't support hyperlinks. There really ought to be a hyperlink datatype as part of the json standard, with the same attributes that html supports: a label, href, rel, maybe more. The label is human-readable, and rel is machine-readable; both provide the semantic information that identifies what the link is for. The url is given by href, of course.

Not having this datatype is a big drawback of json for RESTful responses. That's why I typically design APIs to use xhtml responses instead. They're just as parsable (just a big bit slower) but they're richer and they allow the API to be tested with a browser that has no knowledge of the semantics of the API. I consider the ability to use the API using a generic client to be a good test of properly implementing HATEOAS.

Why would an URL type be useful? If JSON responses are {key:value,...}, in both ends 'key' has a meaning, and when you receive {'link':'http://...}, you deal with 'link'... I'm confused.

It would be useful because it would provide a standard way of expressing a hyperlink. URLs are a standard way of expressing the location of a resource, HTTP is a standard mechanism for interacting with resources, but there are no widely-used standards for expressing "here's a URL". XLink and RDF tried to become standards for that, but they haven't caught on. The text/html content type (and its close relatives) are widely understood and include a couple of syntaxes for different types of links, and that's why I like xhtml as my API content type. If JSON had a standard widely understood syntax for links I'd happily switch over since JSON is certainly more popular as a RESTful API content type.

Imagine where we would be if every website expressed links using a different syntax, and browsers had to be explicitly programmed to understand a given website's syntax in order to use its links. The web couldn't exist that way.

XHTML is great for web pages, but it's a poor format if you want to transmit very structured data. There's no way in X(HTML) to say "this is a user", "this is user X's name", "this is user X's email address", etc.

Frankly, if I GET an URL from your API describing a certain user's profile, and I get a blob of unstructured text, I won't use your service for long.

XHTML + RDFa is a different case, but that's hardly well understood, especially the specific ontologies. It's really no better ATM than using a custom JSON based format.

    <div data-role="user">
        <span data-role="name">...</span>
        <span data-role="email">...</span>
    </div>

In general, I agree with you that XHTML isn't a great format for structured data. One advantage that XML has over JSON is the ability to attach attributes to data elements. I find that useful, and much easier to use than JSON's best alternative which is to turn a simple data element into a dictionary object.

    { key: "value" }

    { key: { attr1: "attr1val", attr2: "attr2val", value: "value" } }

    <div>value</div>

    <div attr1="attr1val" attr2="attr2val">value</div>

In the XML markup, you can retrieve the value the same way in both cases. With the JSON markup you have to use different syntax to retrieve the value depending upon whether or not there are attributes, which means you'll wind up always using nested objects if the attributes are optional, just to have consistent syntax.

What's odd about this is that in Javascript, attributes (aka Properties) can be attached to anything. You want your string variable to have some properties? No problem. You want some of those properties to be functions? Go for it. You want your function to have methods? Enjoy. I'm surprised that JSON didn't include this capability, since it exists in Javascript and is also a big distinguishing factor between JSON and XML.

Getting back to hyperlinks as a datatype, JSON uses "" for strings, [] for lists, {} for dictionaries/objects, and key: value for key/value pairs. Why not add <...> for hyperlinks as a special kind of string? The ... could just be a url, or it could be a url followed by a comma-separated list of standard attributes like rel="..." and label="...". It's a small addition, but I think if it was right there in the markup syntax it would become widely used, and software which parses and works with JSON could depend upon it being there and build higher-level functionality on top of it.

    <div data-role="user">
        <span data-role="name">...</span>
        <span data-role="email">...</span>
    </div>

Those attributes aren't defined in the XHTML spec. You've essentially created a new (custom) format on top of XHTML. It's no better than any of the custom formats based on JSON.

Now every JSON parser would have to embed a Javascript interpreter to be complete. That would make it completely impossible to implement in a huge number of cases, not to mention the headaches with security (the halting problem, for example) and performance.

data-* is an HTML5 attribute: http://dev.w3.org/html5/spec/Overview.html#embedding-custom-...

The standard says that specific data-* attributes are only intended to be used by the site that generates the markup, but I think it's fair to say that an API using them can give semantic meaning to them for the use by any code using the API, without violating the standard.

Sure, and the same can be done in JSON.

XML doesn't support hyperlinks either. In fact, that was my point. JSON or XML are not formats, just transport mechanisms. You need a format (which may be encoded in JSON or not) that defines those semantics.

Personally, I drank the RDF kool-aid some time ago, and I think the best solution for many services is either RDFa augmented HTML, or Turtle for a more "pure" data response.

The base definition of XML doesn't specify hyperlinks. But XLink does, and because XML has namespaces, it can be integrated into any other namespace-aware XML application without risk of collisions: http://www.w3.org/TR/xlink/

> The base definition of XML doesn't specify hyperlinks.

No definition of XML does.

> But XLink does

By having the client understand xlink exists and accessing xlink attributes you get links. This is no different than specifying that there are URL values corresponding to specific keys in your JSON-derived media type.

An XLink-containing document is a media type derived from XML in the exact same manner.

> and because XML has namespaces, it can be integrated into any other namespace-aware XML application without risk of collisions: http://www.w3.org/TR/xlink/

Not really relevant to the discussion, is it?

XML doesn't support hyperlinks, but I didn't say I use XML. I use xhtml, which is a specific content type that is both widely understood by existing programs and also has explicit and standardized support for hyperlinks.

I liked RDF for a while too. I even came close to designing and building an RDF database for my employer at the time. Too bad it didn't catch on.

> I understand the appeal of using json, but it doesn't support hyperlinks. There really ought to be a hyperlink datatype as part of the json standard

No, there's no need for it, you can just define it in your own media type, which is expressed in JSON. JSON is a meta-format with a few datatypes, XML is a meta-format with a single datatype (strings).

> Not having this datatype is a big drawback of json for RESTful responses.

No, it's not.

> I consider the ability to use the API using a generic client to be a good test of properly implementing HATEOAS.

That's nonsense. Your browser is not a generic client, it's an interface to a user. There's nothing "generic client" about a user in front of a browser. And as far as the actual users of the API (code) are concerned, your urls could be in `a href` or in `span data-whatever` it makes no difference, as long as they're built with that understanding in mind.

And that understanding is the API's media types definition.

> No, there's no need for it, you can just define it in your own media type

I don't want to define my own media type, because if I define my own media type only clients that are designed to understand my media type can use my API. I want to use a media type that clients can already interact with in standard ways. I want my clients to be able to do something like this:

    var url = hyperlink(resourceData, linkRel).href;

That way they need to know the value of linkRel they're interested in (semantic knowledge of my API) but nothing about the structure of my resourceData object.

When I use xhtml, this works (with jQuery):

    var url = $(resourceData).find("a[rel=" + linkRel + "]").attr("href");

The point is that just as XHTML is a format built over XML, there can be (and are) standard formats built over JSON. You don't need URL support in JSON, just like you don't have it in XML and yet you can still identify links in a format based on it.

For example, the JSON Activity Streams[1] is a standard format, supported by plenty of 'big names' (Google, Opera, Gowalla, etc), which defines a schema under which certain keys ("url") are to be considered URLs/links.

[1]: http://activitystrea.ms/

Thanks for the link, but you're proving my point: if I'm building an application that consumes Activity Stream resources, and also other kinds of resources, I have to have a different interpreter to understand and follow links in these different resource types. I don't have to do that for strings, numbers, lists, or dictionaries because those are standard datatypes in JSON. I think we're at a point now where hyperlinks should be a standard datatype too.

A second-best alternative would be a standard way to express hyperlinks in JSON using the existing datatypes. I don't think a key:value pair with a key named 'url' is sufficient though; hyperlinks need metainfo so you can differentiate them from each other and give them semantic meaning, like the 'rel' attribute does in xhtml. I think labels are important too, though they're not always needed.

The problem with this approach is that it's reinventing RDF and XLink in JSON, and RDF and XLink have already failed to be broadly adopted. I think part of the problem with them is the need for an add-on interpreter in addition to the syntax interpreter. If RDF or XLink interpreters were baked-into HTML and XML parsers so that the linking info they provide were as much a part of the syntax as elements, attributes, and strings, they might have become widely used.

> if I'm building an application that consumes Activity Stream resources, and also other kinds of resources, I have to have a different interpreter to understand and follow links in these different resource types. I don't have to do that for strings, numbers, lists, or dictionaries because those are standard datatypes in JSON. I think we're at a point now where hyperlinks should be a standard datatype too.

But you still need to know what that number, list or dictionary means. By itself, what does [3, 5, 6, 2] mean? Nothing. Likewise, you'll know that string X is a link because you know the format.

And the exact problem exists with XLink. Let's say I'm parsing a user profile and there's an XLink there. To where does that link point to? The user's personal website? To his mother's profile? To a song he likes?

XLink is only useful if you don't care and are just displaying it to the user. Most of these APIs are supposed to be consumed by machines, hence they need to have more structured formats. Having that, XLink is irrelevant.

> hyperlinks need metainfo so you can differentiate them from each other and give them semantic meaning, like the 'rel' attribute does in xhtml.

As I said previously, that's provided by the format, which the client needs to understand anyway. I know an 'url' inside an 'Image' object represents the URI I can access the Image data from. I know an 'url' inside a 'Friend' object represents that person's profile page, etc.

> The problem with this approach is that it's reinventing RDF and XLink in JSON, and RDF and XLink have already failed to be broadly adopted. I think part of the problem with them is the need for an add-on interpreter in addition to the syntax interpreter. If RDF or XLink interpreters were baked-into HTML and XML parsers so that the linking info they provide were as much a part of the syntax as elements, attributes, and strings, they might have become widely used.

RDF is another example of a format that's useless by itself. Sure, you know that X is an URL, but an URL of what? The client needs to understand the domain ontology. Knowing that, it's obvious what is and isn't an URL.

[3, 5, 6, 2] is a list; I have standard tools for iteration over the list and for getting the length of the list. These allow the creation of other tools that build upon the basic tools: filtering, transformation, reduction, unions, differences, etc. I have this rich toolset for working with lists because lists are a standard datatype; if the syntax for expressing a list were different for every list I wanted to work with, none of these tools could exist.

The 'meaning' of the list, within the context of a specific API, is of course specific to that API. That's the semantic meaning I've been mentioning. My ideal is where you only need to document the semantic meaning, and not the syntax that is used to represent that meaning. The syntax should be standardized.

But URLs are always represented as strings, even in XLinks, HTML and such. Adding special syntax wouldn't make it more structured. Every existing toolset for working with URLs accepts them as strings.

The other part, identifying a certain string as an URL, is much the same as identifying the 'meaning' of the list - it can and should be done by the higher-level format that sits on top of JSON.

> The request is not transmitted in JSON. So it's not JSON-RPC at least.

I don't count that as a positive, since it would at least prevent them from calling it restful.

> The URI is RESTful. (Explicit collection and member actions, with common namespace.)

URIs can not be RESTful, this does not even make sense.

> Supports both JSON and XML. (Internet media types)

Supporting "JSON" and "XML" is completely useless: they're meta-format, in and of itself outputting "JSON" is completely meaningless as it does not tell the client anything.

Defining the exact media types returned (which this API description barely does) is the vast majority of a RESTful application's documentation. In fact, it should be all of the documentation save for a single URL, which is the API's root entry point.

> Bitcoinica API utilizes three of the four RESTful Web Services methods - GET, POST and DELETE. (HTTP methods)

Better, but still not sufficient to make an API restful. Plus orders are created via a POST, that's not correct, the semantics of POST are updating (creation is PUT)

> But I'm not sure about the hypertext part, because I don't understand what hypertext means here.

And you don't think that might be an issue in your judgment?

> Is Bitcoinica's interface considered hypertext-driven?

No, and being hypertext-driven is the most important criteria of a RESTful application.

POST semantics can be used to CREATE as well. And PUT can also be used to UPDATE.

PUT semantics are more like "update_or_create". POST is like "create_child".

http://stackoverflow.com/questions/630453/put-vs-post-in-res...

(I'd upvote you more but we're in the minority.)

I wish people would read about REST [0] before they use the term. Proper use of HTTP is only one prerequisite of an REST over HTTP implementation.

[0]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... is a common point missed by most folks.

Reply on news.ycombinator.com