Re: Assistance needed by a new Hydra user for a large public REST API

Hi John,
Nice to find you.
I think I can partially and in general answer to your questions based on
the experience I had trying to design an "hypermedia-driven" REST API from
scratch. I found useful to read and follow the opened issues on the Github
account <https://github.com/HydraCG/Specifications/issues>.

Furthermore, considering the aim of so called "smart clients" browsing
self-descriptive APIs, I have learned that the thing can work if the API is
fully compliant to certain REST constraints, and in particular HATEOAS. So
it is supposed to be that "a client interacts with a network application
entirely through hypermedia *provided dynamically by application servers*"
(quote Wikipedia). Applying this constraint makes classes really simple
because "recursion" inside documents is handled by providing a link to the
user to reach whatever other information he/she needs (e.g. hypermedia).
Considering your example:


2015-07-18 19:48 GMT+02:00 John Tibbetts <john.tibbetts@kinexis.com>:

>
>
> GET /record_of_performance
>
> The response media type is composed of representations of the following
> data:
>
> Student information
> Institution information
> Program information (e.g. MBA)
> Course information (collection of all courses taken)
> Competency information (collection of competencies accrued within a course)
>
>
>
>
​What do you mean with "representations"? Plain strings, i.e. JSON-LD with
no hypermedia? Links? Linked data?

The only way I know to shape this document to be easily "hydra-compliant"
is:

GET /record_of_performance

{
    "student information": <link to the /student/:id resource>,
    "institution information": <link to /institution/:id resource>,
    "program information": {
        "program type": <link to the /program/:id resource>,
        "course information": [ <link to /course/:id>, <link to
course/:id>,...
        ],
        ...
    }
}

In this kind of more structured documents, we substituted all the "string"
information with hypermedia, using only very simple classes. You can easily
describe (maybe you can find some little problems with the collection, as
far as I know that part is not completely defined by the draft yet) the
structure above with the Hydra specs. This kind of approach in describing
resources can be easily consumed by smart and traditional client, the only
major difference we found is obviously that the basic resources' URLs are
hit more often (but it actually we also found out that can be an
optimization advantage for our servers).
Obviously this drives to a completely different end-user experience, but I
think your users eventually will definetly appreciate it. On the other
side, applying Hydra to non-HATEOS APIs can be complicated as you rightly
underlined, probably because it is not a complete specs yet.

If you design your API considering hypermedia from the beginning (something
we call "full-HATEOS"), then it's pretty straightforward to apply the Hydra
ApiDocumentation to such a design. This is the way we interpreted and
applied the Hydra specs, so, I repeat, it can be a partial interpretation
or something that fits for our purpose and cannot be generally applied to
other cases. A full-HATEAOS design is the only complete solution I know for
your question, but maybe somebody has something that involves less
refactoring of your API and can help you differently.
Regards.​


-- 
¤ acM ¤
Lorenzo
Moriondo
@lorenzogotuned
​https://it.linkedin.com/in/lorenzomoriondo​