Standards.REST: A Collection of HTTP/REST API Standards and Specs

The idea originally was just to show RFC's but I think we can start expanding the project now.

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.

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.

The last time I looked at Open API it was really hard to model a proper REST (HATEOAS) API

check out https://openapi.tools

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.

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

Perhaps you should make that URL scheme a standard?

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

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

A client: https://github.com/evert/ketting

This begs the question: Has anyone here seen .rest used in the restaurant industry?

tell that to all the .io domains that have nothing to do with the BIOT