[tlrobinson]

"JSON doesn’t have links."

JSON doesn't, but HTTP does. Why not use Link headers?

[AffableSpatula]

Link header parsers are far less ubiquitous than json, and Link headers aren't very good for use cases like representing links that come from items in a collection, there are also issues relating to the maximum feasible size for HTTP headers and/or the header block as a whole.

Link relations are useful for adding links to media types that can't support links (e.g. images, etc), and for layering protocols (e.g. Linked Cache Invalidation), but for normal APIs it makes your clients life much easier if you just put them in the body.

[MatthewPhillips]

Would this be a better fit as part of an OPTIONS request?

OPTIONS /orders

  {
    "GET": {
      "description": "All the orders."
      "links": {
        "self": { "href": "/orders" },
        "next": { "href": "/orders?page=2" },
        "find": { "href": "/orders{?id}", "templated": true },
        "admin": [
          { "href": "/admins/2", "title": "Fred" },
          { "href": "/admins/5", "title": "Kate" }
        ]
      }
    }
  }

[bct]

Here's one opinion on that: http://www.mnot.net/blog/2012/10/29/NO_OPTIONS

[steveklabnik]

That's another option, yes.