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

Hi Lorenzo,

First let my thank you for the quick response.  The very first suggestion you made (reading the open issues in Github) has already opened up new vistas for me.  In fact, I now think that I should come up the learning curve further before even restating my question.

Still I can’t help but give some preliminary impressions.  

I totally understand your point about the HATEOAS client; e.g. as shown in:

> 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>,...
>         ],
>         ...
>     }
> }

I have no doubt Hydra is suited to this model as it currently stands.

But the nature of the problem space (distributing secure, signed college transcripts) is not compatible with the notion of progressive discovery.  An essential business rule is that a request for a transcript invokes an atomic operation that returns all parts of your transcript.  Just think of when you request a transcript to be sent to some new institution; say a graduate school or an employment opportunity.  You request the transcript from the registrar.  The registrar has strict rules about assembling the entire academic record into a single document.  (This is not unlike assembling all terms of a business contract in a single document.  You know the lawyers wording like: “we represent this document is complete and entire” or some such thing).  That transcript will include crucial information about the institution, user, program of study, course completion, perhaps, in newer learning model the course is composed of discrete ‘badge able’ competencies, and your level of performance in these activities.  Maybe it also includes a statement of extracurriculars—depends on the institution.

This completed document is then signed and safely delivered.

That’s the type of service I need to describe.

Since writing the note yesterday I’ve found some Hydra examples which are pointing me towards a possible solution but I think I will give it a try before asking more questions.

But thanks for the assistance and warm welcome!

John


> On Jul 20, 2015, at 2:02 AM, Lorenzo Moriondo <tunedconsulting@gmail.com> wrote:
> 
> 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 <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 <mailto: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 <https://it.linkedin.com/in/lorenzomoriondo>​