5 ms·

The request is not transmitted in JSON. So it's not JSON-RPC at least. http://en.wikipedia.org/wiki/Representational_state_transfer#RESTful_web_services http:/

The request is not transmitted in JSON. So it's not JSON-RPC at least. http://en.wikipedia.org/wiki/Representational_state_transfer#RESTful_web_services 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?

icebraining 15y ago
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.
- DougWebb 15y ago
  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.
  - swah 15y ago
    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://... http://...}, you deal with 'link'... I'm confused.
    - DougWebb 15y ago
      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.
      - icebraining 15y ago
masklinn 15y ago
> 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.
- mckoss 15y ago
  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-rest http://stackoverflow.com/questions/630453/put-vs-post-in-res...
- deleted 15y ago
  [deleted]

icebraining 15y ago

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.

DougWebb 15y ago
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.
- swah 15y ago
  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://... http://...}, you deal with 'link'... I'm confused.
  - DougWebb 15y ago
    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.
    - icebraining 15y ago

masklinn 15y ago

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

mckoss 15y ago
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-rest http://stackoverflow.com/questions/630453/put-vs-post-in-res...
deleted 15y ago
[deleted]