News for hackers. Stuff that matters.
Re:Show HN: Pass a URL, get summarized content by despinozist on Sunday February 28, 2016 @01:02PM (#11191660)
You should render the output as actual JSONAPI (http://jsonapi.org):

    {
      "links": {
        "self": "...",
        "prev": "...",
        "next": "..."
      },
      "data": [],
      "included": []
    }
So that we can discover the API beyond the form. Use http://www.iana.org/assignments/link-relations/link-relation... as the starting point for link relations ideas.
Re:Show HN: Pass a URL, get summarized content by wyldfire on Sunday February 28, 2016 @01:09PM (#11191691)
I was pretty quick to knee jerk ask myself "Why is this any better than any other schema?" (I was not convinced that "API discovery" was, by itself, a good enough case).

Then I read the very practical first sentence of the jsonapi page: "If you've ever argued with your team about the way your JSON responses should be formatted, JSON API can be your anti-bikeshedding tool." That alone is probably huge. May not mean much for individual projects, but it's good enough for me to bookmark for the future.

Re:Show HN: Pass a URL, get summarized content by fishnchips on Sunday February 28, 2016 @02:07PM (#11191890)
Can't help but think of https://xkcd.com/927/ ;)

Not sure if standards like this can prevent bikeshedding. You can always bikeshed about the need to stick to any particular standard. One counterexample to what I'm saying may be one standard Go language formatting with gofmt but that was introduced very early on and became a part of the culture. Too late for that with JSON APIs.

Re:Show HN: Pass a URL, get summarized content by despinozist on Sunday February 28, 2016 @01:29PM (#11191775)
Ya I was like why all teh downvotes y'all?

Then I realized I had no actual link ("http://") in my initial post.

I tend to assume all have read exactly what I have read. JSONAPI has huge implications for distributed systems architecture.

Re:Show HN: Pass a URL, get summarized content by developer2 on Sunday February 28, 2016 @11:37PM (#11193612)
I'd like to point out that this formatting convention is not a widespread standard. "You should" is biased towards making life simpler for a small number of people who have used the format before, while complicating and bloating your API responses - for both the developer(s) and consumers of your API.

Consumers are now expected to add a full library to their project to parse/understand the JSON responses. Also, implementation overload for many languages: http://jsonapi.org/implementations/

Re:Show HN: Pass a URL, get summarized content by jamiesonbecker on Sunday February 28, 2016 @06:05PM (#11192814)
> You should [...]

At least there's no namespacing or DTD's!

JSON plus a loose adherence to REST won out over SOAP/XML-RPC/WSDL/etc because of its simplicity. Services discovery seems to be a solution in search of a problem.

Even the simple idea of embedded links, with apologies to Dr. Fielding, seem to be a less critical component of REST than was initially believed, since very few modern REST API's actually provide them.

Re:Show HN: Pass a URL, get summarized content by dragonwriter on Monday February 29, 2016 @01:10AM (#11193879)
Very few modern "REST" APIs have even a remote resemblance to the REST architecture described by Fielding, it's mostly just RPC over HTML with data in an specialized subset of JSON or XML that is specified per endpoint out-of-band rather than indicated by media type.

I really wish people would stop calling it REST, since that Rob's the meaning from the term.

Re:Show HN: Pass a URL, get summarized content by jamiesonbecker on Monday February 29, 2016 @12:01PM (#11196580)
To some point, I agree! I also used to be a REST purist, but I've become more pragmatic in recent years.

Some crucial points that are often preserved even in today's API's that distinguish them from RPC:

- Any REST API will have the concept of resources that are acted upon by HTTP verbs (methods), instead of RPC-style calling a method named in the URI.

- statelessness (no session state assumed on the server)

- use of HTTP status codes

- resource path generally indicates hierarchy or at least a specific 'one path to this representation'

- broad use of existing HTTP headers for metadata instead of a separate "envelope" in the body as in SOAP

- use of common HTTP headers such as Authorization rather than cookies or other carriers of state

Many of the other compromises are not always because of ignorances, but in order to be broadly useful in the most common cases.

I don't disagree with your point about not calling it REST, because this trend does diverge from Dr. Fielding's dissertation in several important areas (for example, content negotiation, as you point out). That's why I prefer the term "loose REST".