Re: My opinion about hydra vocabulary

Meanwhile I learned RDF, more REST, and other architecture solutions. After
that I checked your hydra core vocab again, and I still have the same
troubles with it. But maybe I just don't understand it fully. (I'll check
you example application when I have more free time.)

If I am correct with your vocab you cannot describe asymmetric
representations of the same resource or property, because it does not
really describe the representation, but just the resource graph itself. For
example by a password you can have a password input field, a password-again
input field and a password-hash-abbr output field representing the same
property. Or by a birthday you can send the date in iso 8601, timestamp,
yyyymmdd, etc... which are different representations of the same property.
By resources you can have much more complex representations of the same
resource, which can be different from each other either, for example their
can contain different properties, different links, or have different
structures, and so on... All of these are not part of the resource graph,
just different representations of resource graph fragments. How do you
intend to model this part of your REST API?


2014-01-24 13:45 GMT+01:00 László Lajos Jánszky <laszlo.janszky@gmail.com>:

> 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.
>