3 ms·

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 s

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
    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.
    - DougWebb 15y ago
      <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.
icebraining 15y ago
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.
- premchai21 15y ago
  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/ http://www.w3.org/TR/xlink/
  - masklinn 15y ago
    > 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/ http://www.w3.org/TR/xlink/ Not really relevant to the discussion, is it?
- DougWebb 15y ago
  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.
masklinn 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 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.
- DougWebb 15y ago
  > 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");
  - icebraining 15y ago
    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/ http://activitystrea.ms/

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
  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.
  - DougWebb 15y ago
    <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.

icebraining 15y ago

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.

premchai21 15y ago
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/ http://www.w3.org/TR/xlink/
- masklinn 15y ago
  > 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/ http://www.w3.org/TR/xlink/ Not really relevant to the discussion, is it?
DougWebb 15y ago
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.

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

DougWebb 15y ago
> 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");
- icebraining 15y ago
  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/ http://activitystrea.ms/