My opinion about hydra vocabulary

Hi everybody!

My name is László (means Ladislav) Jánszky and I'm glad to be part of this
group. I have my own opinion about Hydra what I'll share with you in the
current post. I propose you to do the same, because everybody has a
different viewpoint, everybody can add his/her knowledge and experience to
our model of REST APIs.

First of all I want to thank you Markus for your work! It is very important
to have a common model for REST APIs because without a common vocabulary we
cannot describe the interface of RESTful applications, and without
descriptions we cannot make tools to ease the development of these
applications by generating at least the API part of them. Your work is a
very good beginning, however I think it is not perfect, and I have
recommendations which can maybe help you to improve it.
Recommendations about the documentation Illustration

The illustration<http://www.markus-lanthaler.com/hydra/spec/latest/core/vocabulary.png>contains
an arrow which is maybe an error its source is the
*Operation*, its target is the *Resource.operations* and its type is
*rdfs:subClassOf*. I don't think that the Operation class is a subClass of
Resource.operations which is a property. Maybe I am wrong with this...

The 2 type of arrows on the illustration are too similar. I think you
should have created an UML class
diagram<http://www.garretwilson.com/%7Emarmox/resources/garretwilson/essays/law/uml_class_diagram.png>instead
of your custom diagram type. It would be easy understandable for
everyone. There are great tools to create such diagrams...
Documentation and examples

I don't think you should restrict the examples to *JSON-LD* only. By
RESTful applications, you can use many different hypermedia types, which
can be used to describe the Hydra classes in a slightly different way than
you do with your media type. For example it can be done with the
*HAL+JSON*<http://stateless.co/hal_specification.html>media type and
the
*self*, *type* and *profile* link
relations<http://www.iana.org/assignments/link-relations/link-relations.xhtml>too...

The Hydra vocabulary is a namespace with classes and interfaces, and it
should be documented as usually classes and interfaces by any namespace or
framework are <http://pages.github.com/>...
Recommendations about classes in the Hydra vocabulary

I thought a lot about how to model REST APIs. From the current Hydra vocab
I learned how to bind the resource classes and their properties with to the
linked data. I think the idea behind this part of the vocabulary is
perfect. Yes we need *Resource*, *Property* and *Link* classes to do this,
and we have to bind these classes with their instances and with the linked
data. I don't think this part can be done better.

I think the other part of the vocab which describes links, operations,
status codes, search queries is not so good. I can offer a better concept I
think.

The REST (representation state transfer) architectural style means that we
should synchronize the application state with the resource state due to
sending representations of each state to the maintainer of the other state.
For example by *GET* requests we send the representation of the resource
state to the client in the body of the *HTTP response* in order to change
the application state. By *PUT* and *POST* requests we send the
representation of the application state to the web service in the body of
the *HTTP request* in order to change the resource state.

Each of these Transfers are part of a bigger thing which is called
Application State Transition. *Application State Transition* consist of
many parts:

   - *Application State Transition*
      - *Current Application State* - this is the current viewpoint of the
      client. A part of this is sent with the Transfer, another part of this is
      used with the Hypermedia to build the next Application State.
      - *Link relation* - this helps to put the current Transition in the
      proper Context. This part of the Transition is used on the client side
      only. For example an* edit* relation with *200* status code means
      that the content of the input fields are now part of the
resource state, so
      they can be used by any representation of the targeted Resource. A
      *delete* relation (haven't found a link relation for this on the IANA
      site) with *204* status code means that the Resource is no longer
      part of the Resource State, so any representation of it can be
deleted from
      the Application State.
      - *Representation State Transfer* - this synchronizes the application
      state and the resource state. By REST the server every time performs and
      Abstract Application State Transition, which result is sent back to the
      client in a Hypermedia format. So this Hypermedia contains the
description
      of the next Application State, that's why they call Hypermedia the Engine
      of the Application State.
         - *Http Request*
            - Http method - this is the identifier of the Method called on
            the Resource instance.
            - URL.path - this is the identifier of the targeted Resource
            instance.
            - URL.query, HTTP headers & cookies - these contain the Context
            of the Abstract Transition. The Context is the unique
viewpoint of the
            client, it can contain authorization headers, pagination
details, sorting
            details, search queries, etc... The Context can modify the
running of the
            Resource Method and so the result of the Abstract
Transition, and so the
            result of the Transition.
            - body - by write requests this contains the Representation of
            the current Application State, which is the Representation
of the relevant
            part of the next Resource State (by valid requests only ofc).
         - *Http Response*
            - *Status* - this is the status of the Abstract Application
            State Transition. It contains *code*, *title* and *description*..
            This part is well described by the vocabulary.
            - HTTP headers & cookies - they can contain the preferred
            settings of the user. For example the name of the client
skin, the default
            item count on a page, etc...
            - body - by read and (sometimes) write requests this contains
            the Representation of the current Resource State, which is the
            Representation of the relevant part of the next Application State.

 Okay so what do we have here? Which part of this desciption interferes
with the current Hydra vocabulary?

   - Links and Operations are not so different, I think the can be the same
   class called Link.
   - The Resources have Methods not Links or Operations. Every Link calls a
   Resource Method, and initiates a server side Abstract Application State
   Transition.
   - Two different Links can call the same Resource Method, they can differ
   in the parameters of the Method. These parameters reflect the different
   viewpoints of the different clients or the different application states of
   the same client. I call that term Context, but it can be called Aspect or
   ViewPoint as well. For example by *GET /users?offset=2&count=10* the *GET
   /users* is the constant part and the *?offset=2&count=10* is the Context
   dependent part. So in this case the client want to display the user list,
   but in a Context of 10 items per page and seeing the second page. Another
   example is, while you are editing your profile on facebook, you can watch
   it from different ViewPoints, you can see it as owner, as acquaintance or
   as a stranger. The Context can contain the following Request modifiers:
      - identification factors for authentication
      - sub-resource filters (pagination&sort, search keywords, filters
      dependent on the authorization - the client should not know of these)
      - property filters (which fields to get from the server, or which
      fields to set on a resource, it can be Context dependent, for example a
      field is readonly by a regular user, but it is editable by an admin....)
   The Context can contain Link Relations as well, but those are not sent
   to the server, so they are not Request modifiers. The API documentation
   should describe them as well, because they are sent back with the
   Hypermedia. So if you define supported Context params by every Method and
   concrete Context params by every link, then the PagedCollection and the Iri
   Templates will be obsolete.
   - I think it will be good to define a Representation class. The
   Representations can contain Links and Representation of Properties. I don't
   have a name for that term yet, but for example you can represent a date
   many different ways, but you store it usually one way in the resource, or
   you can represent a property name many different ways, e.g. firstName,
   first-name, givenName, név (in Hungarian), etc... The Resources can contain
   Methods and Properties. By creating a Documentation, we should describe the
   relevant part of the Representations and the Resources as well. The current
   vocabulary describes only the Resources well, but by describing the
   Representations (which are the available options by Resources restricted to
   the current ViewPoint of the client) there are many different classes for
   the same problem domain (TemplatedLink, IriTemplateMapping, IriTemplate,
   PagedCollection, CreateResourceOperation, ReplaceResourceOperation,
   DeleteResourceOperation), but not a single, which can generally solve it
   (Representation, Context, Link with LinkRelations).

 My REST vocabulary is currently a draft too, I have to create a proof of
concept application, but I think its approach is more general than Hydra
currently possess, so it could be part of the next release of Hydra. I was
too tired to write a more detailed post about it, I am not sure whether
this is understandable or not, please write a feedback.