News for hackers. Stuff that matters.
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by somada141 on Saturday May 18, 2019 @01:56AM (#19945906)
I'm a little surprised I didn't see the JSON:API spec [1] on there (no affiliation). While by no means a silver bullet my team has adopted it for both internal and public APIs and our clients have been quite happy having a standardised API like that.

In addition it is fairly-well supported by community packages (at least in Pythonland, e.g., marshmallow-jsonapi [2]) so it fit quite nicely in our stack while we could incrementally come up with v2 APIs that implement it.

Lastly, the spec does a semi-decent job, again no silver-bullet, of defining more advanced API features like filtering, sorting, field-selection, etc in a way that brings a lot of the GraphQL perks into REST.

[1] https://jsonapi.org/ [2] https://github.com/marshmallow-code/marshmallow-jsonapi

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by rocketpastsix on Saturday May 18, 2019 @08:28AM (#19947042)
The idea originally was just to show RFC's but I think we can start expanding the project now.
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by somada141 on Saturday May 18, 2019 @08:41AM (#19947081)
Ah sorry didn't realise it was supposed to be limited to RFCs. I suppose JSON:API would fit the `A collection of standards and specifications` title :).
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by jypepin on Friday May 17, 2019 @04:44PM (#19943388)
This doesn't seem like it's much helpful. If someone is building a new API and want a list of standard/best practices to follow, something like OpenAPI[0] would be much more helpful.

Here, I'm not sure what one would do with a list of RFCs?

[0] https://swagger.io/resources/open-api/

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by smt88 on Friday May 17, 2019 @05:40PM (#19943828)
Open API Spec is just a format for documenting HTTP APIs. It has no opinion on how you design your API, whether it be RESTful or not.
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by M2Ys4U on Friday May 17, 2019 @07:11PM (#19944461)
The last time I looked at Open API it was really hard to model a proper REST (HATEOAS) API
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by treve on Tuesday May 21, 2019 @09:47AM (#19970073)
Still is
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by kbenson on Friday May 17, 2019 @05:00PM (#19943525)
I agree that OpenAPI is how I would prefer to see an API documented and defined (especially since there are tools to allow you to use a good spec to automatically generate your client routines), but I think many these RFCs are a bit different, in that they may define how records should show relations to each other, or how to use Oath, etc, which is something OpenAPI documents, but not something it prescribes.

Where OpenAPI defined how to implement a client or server interface for an API, these RFCs seem to define some best practices for how you would do so. That is, if OpenAPI is analogous to a dump of a database schema, these RFCs are more analogous to a set of best practices on database naming, data types to use, which levels of normalization are best for which types of data, etc.

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by rocketpastsix on Saturday May 18, 2019 @08:34AM (#19947061)
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by rubyn00bie on Friday May 17, 2019 @04:36PM (#19943333)
Hmmm... not to be a curmudgeon, but will this help much? Or like what is the intended purpose of this, awareness? Why were these RFCs chosen? I feel like the majority of folks who would take interest in this would already be browsing RFCs. Additionally, this would be more useful it contained (I didn’t see any from my phone) links to example implementations or discussions about the RFC.

I appreciate the work, and thought so far, I was just super stoked for like “MOAR infos,” and then didn’t really get any so I’m a bit disappointed ;_; or maybe I’m just missing something like usual?

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by exfed on Friday May 17, 2019 @05:17PM (#19943650)
I think the take-away is that the Web (with a capital W), even though it's what all the cool kids are doing these days, is really just a collection of real actual standards established by real actual standards bodies, run by real actual Engineers. There are plenty of folks out there who don't give the Web much credence, and would rather shout at those kids to just get off their lawn.

Maybe I'm over-stating the value, but it's good to remember that, as software and automation becomes more ubiquitous, good standards and good engineering are going to get more and more important.

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by geezerjay on Saturday May 18, 2019 @02:24AM (#19946007)
> Hmmm... not to be a curmudgeon, but will this help much? Or like what is the intended purpose of this, awareness?

What's the difference? Developers can only leverage existing technology if they are aware they exist, and unfortunately specs such as the "home document for HTTP APIs" draft aren't publicized that often, so developers tend to waste time reinventing the wheel.

> Additionally, this would be more useful it contained (I didn’t see any from my phone) links to example implementations or discussions about the RFC.

Typically specs already include examples. For example, picking up again the "home document for HTTP APIs" draft, section 2 starts off with a clear example of such a document.

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by the_arun on Friday May 17, 2019 @09:37PM (#19945058)
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by Malic on Friday May 17, 2019 @04:45PM (#19943396)
I kinda wish the domain was "rest.standards" instead to set the pattern of "*.standards" would be where you found such things.
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by pgwhalen on Friday May 17, 2019 @08:33PM (#19944843)
Perhaps you should make that URL scheme a standard?
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by nwatson on Friday May 17, 2019 @06:14PM (#19944097)
No HATEOAS? https://en.wikipedia.org/wiki/HATEOAS

I don't think full-on HATEOAS is practical, and blog (https://jeffknupp.com/blog/2014/06/03/why-i-hate-hateoas/) says it well: "When designing a hypermedia API [per HATEOAS standards], you're really designing for a client that does not, and will never, exist." There are some good ideas there though.

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by geezerjay on Saturday May 18, 2019 @02:16AM (#19945976)
> No HATEOAS? https://en.wikipedia.org/wiki/HATEOAS

HATEOAS is not a standard nora specification. It's a basic part of the REST architecture style.

> "When designing a hypermedia API [per HATEOAS standards], you're really designing for a client that does not, and will never, exist."

I don't believe this is factual or even conceivable. Arguably, OData speficies a standard that designs clients and servers that are full-on REST (per HATEOAS standards) and it does exist and is used in the wild for some years now.

Additionally, there are other standards and specs that do help to implement full-on REST, such as HAL or JSON-LD.

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by jmull on Friday May 17, 2019 @09:24PM (#19945020)
I'm not sure the criticism in that blog has much to with anything. HATEOAS is about an approach to managing application state, not self-documenting APIs.

I suppose it still gets at the big problem with a restful approach: nobody really gets it.

(Personally, I think there are some great ideas in that dissertation, but HATEOAS isn't one of them. At least as far as I can tell.)

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by naasking on Friday May 17, 2019 @11:50PM (#19945478)
HATEOAS is a good idea as well. It formalizes an idiom for schema upgrade and discovery.
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by treve on Tuesday May 21, 2019 @09:49AM (#19970093)
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by dmitriid on Saturday May 18, 2019 @12:11AM (#19945545)
These two resources are a much much much bigger help:

- HTTP decision diagram (click around, every section is explained with links to specs) https://github.com/for-GET/http-decision-diagram/blob/master...

- Know your HTTP well: https://github.com/for-GET/know-your-http-well

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by mxschumacher on Saturday May 18, 2019 @09:19AM (#19947251)
Zalando's REST API resource is quite helpful: https://opensource.zalando.com/restful-api-guidelines/#intro...
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by hughes on Friday May 17, 2019 @05:16PM (#19943638)
> "The .rest gTLD will provide an online zone for restaurants and corollary entities..." [1]

As interesting and useful as this may be, it seems to be a misuse of the chosen TLD.

[1] https://icannwiki.org/.rest

Edit: looks like I was wrong about this one!

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by afarrell on Friday May 17, 2019 @05:19PM (#19943664)
This begs the question: Has anyone here seen .rest used in the restaurant industry?
Re:Standards.REST: A Collection of HTTP/REST API Standards a... by 1f60c on Friday May 17, 2019 @05:50PM (#19943908)
I have not, but

  site:rest
gives several hits[0]

[0]: https://www.startpage.com/do/search?query=site%3Arest

Re:Standards.REST: A Collection of HTTP/REST API Standards a... by pennaMan on Friday May 17, 2019 @05:19PM (#19943671)
tell that to all the .io domains that have nothing to do with the BIOT