5 ms·

While some of the tips are useful, I'd much rather see them written with JSON rather than XML. JSON has long been an industry standard. XML is bloated, almost n

While some of the tips are useful, I'd much rather see them written with JSON rather than XML. JSON has long been an industry standard. XML is bloated, almost no one uses it anymore. http://restcookbook.com/Mediatypes/json/ http://restcookbook.com/Mediatypes/json/ says "There is no predefined way to deal with link discovery in JSON". I'm surprised it doesn't even mention JSON Schema (http://json-schema.org/ http://json-schema.org/) or JSON API (http://jsonapi.org/ http://jsonapi.org/), which are not official standards but allow you to write machine understandable and discoverable API. If the author wants to promote standards, I think it would be better to look at what the world is using and then put together a guide that explains how to use JSON-LD and other W3C proposals.

jaytaph 11y ago
I think some of the articles actually talk about json-hal and ld. Not sure about schema. The examples are in XML because json is, (and I believe at this point), still not stricly an (accepted) hypermedia capable format, thus not adhering the HATEOAS constraint, and thus cannot be restful. But to be honest, I'd prefer JSON over XML anytime. Please, if you have any idea's on how to improve the site, the whole idea was to set up a small set of articles which others could help out expanding. It turned out that not many people actually posted their idea's (or even complete posts), so what you see on the site is pretty much the same thing as 2-3 years ago. I'd love some more PR's on expanding with up-to-date technologies and techniques (even those who aren't truly restful)
- deathanatos 11y ago
  > The examples are in XML because json is, (and I believe at this point), still not stricly an (accepted) hypermedia capable format, thus not adhering the HATEOAS constraint, and thus cannot be restful. But to be honest, I'd prefer JSON over XML anytime. What exactly is the criteria of being a "hypermedia capable format"? The linked website gives an example of how the response on a bank-account like API might include links to other actions; XML and JSON seem equally capable here, as they can both encode links. He mentions on another page, > Unfortunately, JSON is not a hypermedia format. There is no predefined way to deal with link discovery in JSON. Is there a predefined way to deal with it in XML? In the earlier example, I had assumed he did exactly what you would do in JSON: make up a field for the purpose. Though, honestly, that would seem to be the purpose of the "Link:" header.
  - JimDabell 11y ago
    > What exactly is the criteria of being a "hypermedia capable format"? One document must be able to link to another. > Is there a predefined way to deal with it in XML? Yes, Xlink: http://www.w3.org/TR/xlink11/ http://www.w3.org/TR/xlink11/ > In the earlier example, I had assumed he did exactly what you would do in JSON: make up a field for the purpose. The problem with this is that it's non-standard and nothing understands it that isn't custom-written for that particular API. > Though, honestly, that would seem to be the purpose of the "Link:" header. Yes and no. Although the Link header is useful, it's not part of the document, it's a transport layer header. REST is transport-layer neutral.
    - awinder 11y ago
      There are a number of specifications that address linking in JSON: * JSON-LD http://www.w3.org/TR/json-ld/ * HAL https://tools.ietf.org/html/draft-kelly-json-hal-06 * Siren https://github.com/kevinswiber/siren * Uber https://rawgit.com/uber-hypermedia/specification/master/uber-hypermedia.html Totally agree on the points against making up a field / format. Using standards where you can is a great way to bring familiarity & common tooling into your APIs. But don't focus too much on XML vs. JSON, use what you need / want, you can find a standard to support it.
    - jurre 11y ago
      HAL solves this issue pretty well, doesn't it?
vdaniuk 11y ago
Are you aware about anything resembling a convention or at least a limited consensus of best practices combining JSON Schema/Api with JSON-LD? That would be immensely useful.
dhuramas 11y ago
"XML is bloated, almost no one uses it anymore." XML bashing is quite common these days. But I'd like to point out that it's the use case that matters when deciding between JSON and XML. Almost all "enterprise" software prefer XML over JSON. https://www.quora.com/Markup-Languages/What-are-the-advantages-of-XML-over-JSON?share=1 https://www.quora.com/Markup-Languages/What-are-the-advantag...
steveklabnik 11y ago
> which are not official standards It depends on what you mean by 'official standards.' We've registered JSON API with IANA, so it's a standard media type, but there hasn't been an RFC yet, as we're basically just finalizing the spec now. (We're in a week-long period of just textual review, conceptually and structurally, it's done.) And given that AMS is going into Rails and Ember Data will default to JSON API out of the box, hopefully we'll have enough usage to actually justify an RFC in a year or so.
- petrbela 11y ago
  Great to hear that Steve! We're actually moving towards the JSON API ~standard~ format and hope it becomes the standard that gets widely used.
  - steveklabnik 11y ago
    Neat! :) And thanks.
firefoxNX11 11y ago
You can submit a pull request on https://github.com/restcookbook/restcookbook https://github.com/restcookbook/restcookbook
collyw 11y ago
I personally find XML more readable than JSON.
- petrbela 11y ago
  I think a huge drawback of XML is it can't differentiate between an element and an array of one. So to "read" it correctly you should read a schema, too.

jaytaph 11y ago

I think some of the articles actually talk about json-hal and ld. Not sure about schema. The examples are in XML because json is, (and I believe at this point), still not stricly an (accepted) hypermedia capable format, thus not adhering the HATEOAS constraint, and thus cannot be restful. But to be honest, I'd prefer JSON over XML anytime. Please, if you have any idea's on how to improve the site, the whole idea was to set up a small set of articles which others could help out expanding. It turned out that not many people actually posted their idea's (or even complete posts), so what you see on the site is pretty much the same thing as 2-3 years ago. I'd love some more PR's on expanding with up-to-date technologies and techniques (even those who aren't truly restful)

deathanatos 11y ago
> The examples are in XML because json is, (and I believe at this point), still not stricly an (accepted) hypermedia capable format, thus not adhering the HATEOAS constraint, and thus cannot be restful. But to be honest, I'd prefer JSON over XML anytime. What exactly is the criteria of being a "hypermedia capable format"? The linked website gives an example of how the response on a bank-account like API might include links to other actions; XML and JSON seem equally capable here, as they can both encode links. He mentions on another page, > Unfortunately, JSON is not a hypermedia format. There is no predefined way to deal with link discovery in JSON. Is there a predefined way to deal with it in XML? In the earlier example, I had assumed he did exactly what you would do in JSON: make up a field for the purpose. Though, honestly, that would seem to be the purpose of the "Link:" header.
- JimDabell 11y ago
  > What exactly is the criteria of being a "hypermedia capable format"? One document must be able to link to another. > Is there a predefined way to deal with it in XML? Yes, Xlink: http://www.w3.org/TR/xlink11/ http://www.w3.org/TR/xlink11/ > In the earlier example, I had assumed he did exactly what you would do in JSON: make up a field for the purpose. The problem with this is that it's non-standard and nothing understands it that isn't custom-written for that particular API. > Though, honestly, that would seem to be the purpose of the "Link:" header. Yes and no. Although the Link header is useful, it's not part of the document, it's a transport layer header. REST is transport-layer neutral.
  - awinder 11y ago
    There are a number of specifications that address linking in JSON: * JSON-LD http://www.w3.org/TR/json-ld/ * HAL https://tools.ietf.org/html/draft-kelly-json-hal-06 * Siren https://github.com/kevinswiber/siren * Uber https://rawgit.com/uber-hypermedia/specification/master/uber-hypermedia.html Totally agree on the points against making up a field / format. Using standards where you can is a great way to bring familiarity & common tooling into your APIs. But don't focus too much on XML vs. JSON, use what you need / want, you can find a standard to support it.
  - jurre 11y ago
    HAL solves this issue pretty well, doesn't it?

vdaniuk 11y ago

Are you aware about anything resembling a convention or at least a limited consensus of best practices combining JSON Schema/Api with JSON-LD? That would be immensely useful.

dhuramas 11y ago

"XML is bloated, almost no one uses it anymore." XML bashing is quite common these days. But I'd like to point out that it's the use case that matters when deciding between JSON and XML. Almost all "enterprise" software prefer XML over JSON. https://www.quora.com/Markup-Languages/What-are-the-advantages-of-XML-over-JSON?share=1 https://www.quora.com/Markup-Languages/What-are-the-advantag...

steveklabnik 11y ago

> which are not official standards It depends on what you mean by 'official standards.' We've registered JSON API with IANA, so it's a standard media type, but there hasn't been an RFC yet, as we're basically just finalizing the spec now. (We're in a week-long period of just textual review, conceptually and structurally, it's done.) And given that AMS is going into Rails and Ember Data will default to JSON API out of the box, hopefully we'll have enough usage to actually justify an RFC in a year or so.

petrbela 11y ago
Great to hear that Steve! We're actually moving towards the JSON API ~standard~ format and hope it becomes the standard that gets widely used.
- steveklabnik 11y ago
  Neat! :) And thanks.

firefoxNX11 11y ago

You can submit a pull request on https://github.com/restcookbook/restcookbook https://github.com/restcookbook/restcookbook

collyw 11y ago

I personally find XML more readable than JSON.

petrbela 11y ago
I think a huge drawback of XML is it can't differentiate between an element and an array of one. So to "read" it correctly you should read a schema, too.