new | ask | show | jobs
jkrejcha 7 days ago  [ - ]

One of the big things too is the encoding of type information using the mechanisms the standard interfaces provide. In HTTP, this is accomplished using media types (through the Accept and Content-Type headers as well as a few related ones). These media types can be standard but they can be vendored too[1].

With something like

   Content-Type: application/json

   {
       "name": "",
       ...
   }
you don't really know much. With something like example/vnd.mycoolapp.user+json, you get typing information (i.e. you know that the representation of /users/me that the server has given you is a JSON variant of a mycoolapp User. (How the types are known is a priori knowledge of the client (but there are standard link relations you can use to reference API documentation, both human-readable and machine-readable)).

A good example of this is your web browser: it knows how to display text/html documents of various character sets, probably knows text/plain, might know application/json.

The best part is? HTTP has a standard mechanism for defining these link relations even if what you have isn't necessarily amenable to link relations[2] (the Link header). You can use that to navigate through a collection (previous, item, collection, etc), get documentation about the API (service-doc, service-desc), find things that are related (related), get STUN and TURN information (ice-server), etc. I doubt very much of this is used in practice, but there are a very rich set of standardized relationships that could be used here.

(A lot of people admittedly assume "using PUT in a couple of places" is doing REST or that not calling all of your method endpoints doAction.pl or whatever is "RESTful" and I think that definition has become so widespread that talking about something that approaches actually doing something that resembles the architectural style tends to require reduplication.)

[1]: https://www.iana.org/assignments/media-types/media-types.xht...

[2]: https://www.iana.org/assignments/link-relations/link-relatio...

smj-edison 7 days ago  [ - ]

This is really quite brilliant! I'm so curious now, do you have examples off the top of your head where you've seen this in practice?

Edit: one other thought, I'm starting to see how the semantic web fits into this vision. Too bad it was too brittle in practice (though the SOLID folks are doing some exciting stuff).

jkrejcha 5 days ago  [ - ]

I can't say I've seen that many examples of APIs that use them richly. You see a little bit of in in specs that require something be done a certain way (WHEP in particular requires you send ICE information in ice-server link relations). Part of it probably stems from the fact that a lot of the tooling was built on top of OpenAPI (which had discriminators built in and so people used that for implementing "sum types"), etc, and part of that comes from the fact that a lot of HTTP-based APIs basically only take the content portion of the response, ignoring the headers basically entirely (outside of maybe redirects).

Relatively speaking I think there aren't that many people that know that it is even really a possibility, let alone use it.

(You even see discussions on even whether the status codes are to be used at all, when they were really purpose-built to be generalizable.)

This partially is self-reinforcing: the server libraries don't do anything with media types generally outside of maybe a "FileResponse"-ish class or function and the client libraries don't tend to implement it because it's not supported.

Part of it too may be that interoperability isn't necessarily an underlying goal.

> one other thought, I'm starting to see how the semantic web fits into this vision. Too bad it was too brittle in practice (though the SOLID folks are doing some exciting stuff).

Indeed! There's a lot of similar ideas with this and you definitely have things you can fit in there. :)