Re: Some practical hints for my first HYDRA implementation

Hi,
​Sure, let's try to explain a little bit better what my situation about
using Hydra is.
I have tried experimenting mixing REST and LD. Hydra happens to be the most
natural (and probably the only by now) solution to describe this mess (: in
a standard way, or I hope so at least. I find Hydra to be a great idea,
because it could be the common standard to integrate (in the sense of
making them communicate together) different technologies around the market
(like plain REST, graphQL, Falcor and SPARQL for example). If different
technologies could leverage on Hydra to be a common metalanguage, it would
be a good deal.
My experiment started from the User eXperience side of an API, trying to
develop an API easily consumable, as the one appreciated by developers.
This API is meant to be used for apps developing and/or to serve third
parties.

I can here describe my user experience design from an API designer point of
view. I have defined my starting endpoints and how the user can navigate my
data in a HATEOAS style, in the design process I have considered to use
Hydra: I want now to implement the framework, to make my API to be
supported by some sort of standard, so that other designers/developers (and
maybe machines) can understand and use it, and I want also all the other
goodies provided by the framework (self-description, possibility for
smart-clients, ...).
In general, given ​the actual layout of my endpoints, how can I (if it's
possible) apply consistently the Hydra classes and properties to the basic
views of my API? Let's brake it down in smaller questions.

I try to explain in the clearest way what the API tries to do, so maybe you
or any other kind readers can give me some hints about where to start. I
have some experience with RDF but my background is Python back-end
developing, so I could be missing some important points.

A) the *entrypoint*:

{
  "@id": "http://hypermedia.projectchronos.eu/hydra/spacecraft/",
  "@type": "EntryPoint",
  "@context": "http://hypermedia.projectchronos.eu/hydra/contexts/EntryPoint",
  "go_to_subsystems":
"http://hypermedia.projectchronos.eu/hydra/spacecraft/subsystems",
  "register_component": "under-construction"
}

It provides two "custom" properties that need to be described in the
vocabulary I think: go_to_subsystems and register_component; in my design
approach are two "paths" that the user can walk to explore the data. In the
ApiDoc I have described the two main classes of objects in my database:
Subsystem and Component. Do I have to describe the custom properties as
"supported properties" of the Entrypoint class?

Because of the HATEOAS style, as a designer I think every endpoint to be a
*view*, not just as an object or a collection of objects. The view can
contain properties whose values can be data, actions or "paths" to follow
(I usually call the go_to_ properties "gate properties").

B) *subsystems* view >

http://hypermedia.projectchronos.eu/hydra/spacecraft/subsystems

it's a Collection of Subsystem objects (types of components). Probably this
is the simplest to describe with Hydra vocabulary, as it is probably the
most pertinent to the framework's principles. The properties inside every
object are only references to make the user to continue exploring the path,
it is mostly only a map or an index.
The view does not serve any data or class of object in a strict sense
though, maybe I am missing something or doing something wrong? Or my
approach is too heterodox?

C) single *Subsystem* view >
/hydra/spacecraft/subsystems?uuid=Spacecraft_Structure
​This is the one with more properties to describe: application/ld+json​, name,
go_to_components, application/n-triples. It is an object of class Subsystem
but it serves no data, only links to RDF resources and the go_to_components
"action" again, to make the user to follow the path. Again this is just a
map/index to the resource related to the Subsystems object.

​D) *components* view: the collection of components that are of type
subsystem​ >
/hydra/spacecraft/components?uuid=Spacecraft_Structure
A collection of Component objects. Here every member is a single component,
but again it's not the complete object with all the data but only an index.
The user to find the single Component has to use the link in @id

E) Single *component* view >
/hydra/spacecraft/components?uuid=3a722d701bf04954af80effcf265e297
​This last one is the actual Component object with all its data
properties, they are all linked to my RDF vocabularies, so I suppose
they don't need ​description.


​This approach is justified by the need to serve for every view the most
concise piece of information possible, relying on multiple calls if the
user needs more information about something (from this principle the use of
views/indexes instead of full objects). ​


Can this kind of design be described by the Hydra framework? This kind of
approach goes beyond objectives and constraints of the framework?


​By now for serving hypermedia it is mostly static <
https://github.com/SpaceAppsXploration/rdfendpoints/tree/master/hydra>.
The SPARQL part use Python RDF-lib based on a triples store running on App
Engine NDB. This choice is the most straightforward to prototype and serve
triples and data from the same datastore.
Is there anything like a Hydra server for Python?
Take a look to H.U.G<https://github.com/timothycrosley/hug>, it's an
Python3+ API server based on Falcon Framewrok.
I was thinking how cool could be to develop a plug-in to make it serving
HYDRA JSON-LD beside JSON.​

​Thanks, group joined.​



> Thanks,
> Markus
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>
​Big thanks!​
​Ciao!​


-- 
¤ acM ¤
Lorenzo
Moriondo
@lorenzogotuned
http://careers.stackoverflow.com/lorenzomoriondo
https://www.linkedin.com/in/lorenzomoriondo
https://github.com/Mec-iS
https://profiles.udacity.com/u/lorenzomoriondo