Add Hydra (JSON-LD) in the API Specs Today section

[dunglas]

Hi,

Hydra is a great spec that supports most of what is expected from a true self-described and auto-discoverable API.

It describes operations, types, properties, if they are readable or writable, errors, pagination, available filters...

Here is an example of what a smart client can do with Hydra (here using API Platform): https://www.youtube.com/watch?v=aTAt0dKOduk

The client in this video is fully dynamic, no code is generated, it is built only by parsing the API documentation at runtime.

Here is another example showcasing a code generator for React and React Native reading an Hydra spec:

The code hasn't been tweaked at all, it's just the JS code generated from the Hydra spec.

Also, because Hydra is built on top of JSON-LD, the actual data is very simple and understandable by a human, here is an example JSON documents it produces:

{
  "@context": "/contexts/Book",
  "@id": "/books/22",
  "@type": "http://schema.org/Book",
  "isbn": "9787660207130",
  "title": "Quam occaecati culpa aut in.",
  "description": "Et aut laborum cupiditate corporis aliquid aut cumque. Non qui est maiores aliquid. Autem qui est velit excepturi et necessitatibus tenetur doloremque.",
  "author": "Prof. Lee Blick PhD",
  "publicationDate": "1988-11-15T00:00:00+00:00",
  "reviews": [
    {
      "@id": "/reviews/115",
      "@type": "http://schema.org/Review",
      "body": "Voluptate nostrum ut ab voluptatem voluptas quia repellat. Dolores repellat et repellat cumque aut tenetur harum vero. Dolores veritatis perspiciatis aut voluptatem ut reprehenderit quibusdam dolorem. Sed inventore aut voluptatem voluptates."
    },
    {
      "@id": "/reviews/114",
      "@type": "http://schema.org/Review",
      "body": "Consequatur a omnis unde ut. Saepe ullam nam placeat pariatur ratione. Corrupti sint quae velit aut est et repudiandae sint. Tempora harum dolor corrupti eos earum mollitia."
    }
  ]
}

Do you think Hydra is worth an entry in the "API Specs Today" section?

[dunglas]

Ok... https://github.com/vasilakisfil/Introspected-REST#1221-hydra

[vasilakisfil]

@dunglas yes Hydra are one of the few (actually don't know any other one) spec that adheres to REST for real. Maybe I should add a note regarding Hydra in section 6 that is described in related literature. Thanks!