| Time |
S |
Nick |
Message |
| 08:38 |
|
|
wsieroci joined #rest |
| 09:31 |
|
|
wsieroci joined #rest |
| 13:04 |
|
|
Haudegen joined #rest |
| 18:53 |
|
|
wsieroci joined #rest |
| 21:33 |
|
|
KevBurnsJr joined #rest |
| 21:58 |
|
KevBurnsJr |
Hello |
| 21:58 |
|
KevBurnsJr |
Anyone have any good resources on documenting media types? |
| 21:59 |
|
KevBurnsJr |
I'm trying to formalize our custom hypermedia format |
| 21:59 |
|
KevBurnsJr |
https://api.vrv.co/core/index |
| 21:59 |
|
KevBurnsJr |
Thinking application/etp+json |
| 22:00 |
|
KevBurnsJr |
or application/vnd.etp.v2+json |
| 22:05 |
|
KevBurnsJr |
Reading ietf media type registration proceedures |
| 22:07 |
|
pdurbin |
trygvis wrote https://trygvis.io/rest-wiki/hypermedia/ if it helps |
| 22:11 |
|
KevBurnsJr |
interesting |
| 22:11 |
|
KevBurnsJr |
I wasn't aware hal was officially registered as application/vnd.hal+json |
| 22:11 |
|
KevBurnsJr |
I assumed it was application/hal+json |
| 22:13 |
|
KevBurnsJr |
For context, I started 4 months ago at a company which uses REST internally using their own informal json format served as application/json |
| 22:14 |
|
KevBurnsJr |
The format is actively in use by dozens of internal services and a wide range of clients on devices from single page web applications to mobile devices and set top boxes |
| 22:15 |
|
KevBurnsJr |
Because the media type has been poorly defined, it lacks support for important features, such as templated links |
| 22:15 |
|
pdurbin |
KevBurnsJr: could you use JSON Schema to document your format? http://json-schema.org . Or maybe there's something better? |
| 22:16 |
|
KevBurnsJr |
Yes, certainly |
| 22:17 |
|
pdurbin |
Here's my brain dump about JSON Schema, which I'm new to: https://github.com/IQSS/dataverse/issues/4378 |
| 22:17 |
|
KevBurnsJr |
There are some important aspects of the media type I want to address specifically and I feel like accompanying documentation would best serve the purpose |
| 22:17 |
|
KevBurnsJr |
For instance: |
| 22:18 |
|
KevBurnsJr |
- All hypermedia controls should be optional. A client should not panic if one is missing and should instead consider it empty |
| 22:18 |
|
pdurbin |
Sorry, what's a control? |
| 22:19 |
|
KevBurnsJr |
an anchor tag or a _links parameter are hypermedia controls |
| 22:20 |
|
pdurbin |
ok, thanks |
| 22:20 |
|
KevBurnsJr |
- Clients SHOULD handle external links gracefully. Presently, many of our clients assume the contents of a link to be a root relative path and probably won't handle full URIs appropriately |
| 22:20 |
|
KevBurnsJr |
- Links may be templated |
| 22:20 |
|
KevBurnsJr |
(which presently they are not) |
| 22:21 |
|
KevBurnsJr |
lack of templated links leads to hacky /locate implementations |
| 22:21 |
|
KevBurnsJr |
where a client makes a request to /locate?account_id=123 |
| 22:21 |
|
KevBurnsJr |
and the endpoint does little more than returning a link to the account /accounts/123 |
| 22:23 |
|
KevBurnsJr |
I feel like an RFC to formalize the media type would provide excellent documentation for developers of hypermedia clients |
| 22:25 |
|
pdurbin |
What do your developers do now, in the absence of an RFC for this sort of thing? Do they look at a wiki or some API docs or Swagger or something? |
| 22:26 |
|
KevBurnsJr |
right now it appears to be completely informa |
| 22:26 |
|
KevBurnsJr |
l |
| 22:27 |
|
pdurbin |
word of mouth :) |
| 22:28 |
|
KevBurnsJr |
We do use swagger and it does include example responses but there is no documentation about how clients are expected to interpret them |
| 22:29 |
|
pdurbin |
It's cool that you're actually using hypermedia. We just send and receive JSON and call it REST. :) |
| 22:30 |
|
KevBurnsJr |
Technically so do we, since the responses are application/json |
| 22:30 |
|
KevBurnsJr |
the responses just happen to contain links |
| 22:30 |
|
KevBurnsJr |
I'm trying to change that |
| 22:31 |
|
KevBurnsJr |
Unfortunately there are pockets within the company which are unhappy with our adoption/implementation of REST |
| 22:32 |
|
KevBurnsJr |
The primary complaint being that the extra round trips introduce a significant amount of latency when using the API from a user facing client |
| 22:33 |
|
KevBurnsJr |
So there's some disagreement over whether new services should adopt our existing REST standards |
| 22:34 |
|
KevBurnsJr |
I believe I can help alleviate those concerns but first the media type must be formally defined |
| 22:34 |
|
KevBurnsJr |
imho |
| 22:41 |
|
pdurbin |
What do they want to use instead? I saw a video once about how gRPC is faster than all the JSON parsing. |
| 22:41 |
|
KevBurnsJr |
I would prefer to use HAL |
| 22:41 |
|
KevBurnsJr |
The format we've chosen is actually closer to Siren |
| 22:42 |
|
KevBurnsJr |
example: https://api.vrv.co/core/index |
| 22:42 |
|
KevBurnsJr |
__class__ is required, similar to Siren |
| 22:42 |
|
KevBurnsJr |
__href__ is a self link |
| 22:42 |
|
KevBurnsJr |
__links__ are GET rel-links |
| 22:42 |
|
KevBurnsJr |
__actions__ are unsafe rel-links |
| 22:44 |
|
pdurbin |
unsafe in what way? |
| 22:44 |
|
KevBurnsJr |
They expect POST/PUT/DELETE requests |
| 22:46 |
|
KevBurnsJr |
There is also a special __class__: "collection" which contains an "items" property referencing an array of objects, each of which contains hypermedia controls. Similar to collection+json |
| 22:48 |
|
KevBurnsJr |
My impression is that the original creator(s) of the format looked at all the available hypermedia types and cherry-picked the concepts they liked |
| 22:49 |
|
pdurbin |
ah, non-read requests. write requests |
| 22:49 |
|
KevBurnsJr |
yes |
| 22:49 |
|
pdurbin |
congrats on the new job, by the way |
| 22:49 |
|
KevBurnsJr |
thanks |
