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

Hi all,

A bit of background: My name is John Tibbetts and I am based in San Francisco.  I’m an integration architect specializing in educational interoperability.  My principal clients are Vitalsource and Coursesmart (now merged) who provide electronic assets, e.g. eTextbooks, for higher education and some K-12.  I’m a very active member in multiple workgroups at IMSGlobal that provides standards for educational institution with more than 200 institutional partners.  IMSGlobal has been an early adopter of JSON-LD and has, over the past two years architected a number of REST APIs that cover such services as Roster, Gradebook interfaces, analytics, eTranscript signing and generation, and Learning Tool Interoperability (LTI).  LTI in particular encompasses the creation of tool bindings (sort of a plugin architecture) between educational institutions and educational software-tool vendors.  The LTI workgroup in particular has been working on a new tool chain to aid in the modeling, collaborating on, validating, publishing (to other tools) these interfaces.

Our ability to create and express the underlying ontologies is in good shape.  (We’re proposing, and have been testing Protege—alternative suggestions welcome!)  But our ability to publish the REST semantics  in a machine-readable form has been haphazard.  In the past we’ve used a hodgepodge of Java property files, custom exports of a UML modeling tool, a maven build process of custom-built scripts.  I’ve been very interested in the Hydra evolution and have now carved out the time to prototype its use for standards creation.  I’ll be presenting interim results at a meeting at the University of Wisconsin in about 30 days time. 

In general, Hydra does way more than our current approach, incorporating things we didn’t even think about.  Since we’re already conversant in JSON-LD we’re part way up the learning curve.  So, in general, we’re thrilled.

But there is a gap—a few minor items that we can cover up with a few extensions to the vocabulary.  But there is one large one—either in Hydra or in my limited understanding of it.

In the example below keep in mind that out goals for machine-readable REST interfaces seem to differ than most of yours.  We’re not in need of dynamic, adaptive clients.  As a standards organization we publish, vet, and expect conformance to architected interfaces.  We want the machine readability to support documentation, validation and other miscellaneous tool support.  (BTW a dynamic client against our interface would be most useful for training users of our APIs—but we expect the predominant usage to be static, production-quality clients.  We need static interfaces to support high performance.  For example, at Vitalsource we process 1 million LTI launches per day—each corresponds to an eTextbook being opened from a browser or some remote device).

So here’s the problem: many of our services are composed of deep composites of entities.  For example, here’s one used for electronic transcript generation:

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)

Note that each of these representations may also be accessed by more atomic operations (GET /student/:id,  GET /course/:id etc) which would give fuller representations.  But the record of performance needs to be grouped in a common envelope because it needs to be signed and managed as a collection.

So my reading (possible misreading) of the core vocabulary, and the diagram in the hydra spec leads me to believe that it deals with flatter resources.  At the top I see that ApiDocumentation supports one Class that is the root resource.  That makes sense—the service itself should have only one root that supports the operations of the service, etc.  But then i would have thought that Class would have ‘supportedClasses' that would allow the structure to recurse.  But I don’t see a mechanism for recursion.

I do understand that a hierarchy is much harder to deal with from a dynamic client--that’s a problem I don’t need solved, though I know it is solvable.   So maybe that’s why none of the examples that I could find showed anything else.

Am I missing something?  Are there counter-examples?

I did try walking through the forum posts for a similar question but there’s a lot of stuff there and I couldn’t find anything.  I am happy to do the research myself if somebody can just point me in the right direction.

Thanks—and I hope to be an active contributor here.

John