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?
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.
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?
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.
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.
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.)
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.
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.
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 :).
27 comments
[ 1186 ms ] story [ 3884 ms ] threadI 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?
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.
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.
Here, I'm not sure what one would do with a list of RFCs?
[0] https://swagger.io/resources/open-api/
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.
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!
[0]: https://www.startpage.com/do/search?query=site%3Arest
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.
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.)
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.
1. https://github.com/Microsoft/api-guidelines/blob/master/Guid...
2. https://cloud.google.com/apis/design/
3. https://mattgemmell.com/api-design/
4. Video from Jim Webber - https://www.youtube.com/watch?v=aQVSzMV8DWc
- 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
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