Hi Juan, The way to specify the contract look pretty clean and nice. I would love to read a few words about the big picture. What is the final scenario? On Mon, Oct 26, 2015 at 4:03 PM, Juan Hernández <jhernand@redhat.com> wrote:

Hello,

I will soon merge the following patches that introduce a new way to specify the contracts of the RESTAPI:

restapi: Introduce metamodel https://gerrit.ovirt.org/45852

restapi: Use metamodel https://gerrit.ovirt.org/46478

restapi: Generate JAX-RS interfaces from model https://gerrit.ovirt.org/47337

Looks pretty much like we are replacing one way of annotating things with another way of specifying things. Could you elaborate what the benefit of that way of description is? How would I customize endpoints with e.g. @Gzip annotations? Would I at the end still have my JAX-RS annotates resource classes?

These patches introduce a new "metamodel" concept, and move the current specification of the RESTAPI based on XML schema and JAX-RS interfaces to a new "model" built on the new metamodel.

What does this mean for you in practical terms? Currently when you want

to introduce or modify one of the data types used by the RESTAPI you start by modifying the XML schema. Once the patches are merged the XML schema will never be touched, as it will be automatically generated from the "model". For example, imagine that you need to add a new "color" attribute to the "VM" entity. To do so with the new model you will have to modify the following file, which is the specification of the "Vm" entity, written as a Java interface:

https://gerrit.ovirt.org/#/c/46478/16/backend/manager/modules/restapi/model/...

In that interface you will have to add a line like this:

String color();

Note that this Java interface is just the specification of the entity, it won't be used at all during runtime. Instead of that the XML schema will be generated from it, and then Java will be generated from the XML schema, as we do today (this will change in the future, but not yet).

Same for the services. If you want to add a new "paint" action to the "Vm" resource then you won't modify the JAX-RS interfaces, instead of that you will modify the following file, which is the specification of the "Vm" service, written as a Java interface:

https://gerrit.ovirt.org/#/c/47337/6/backend/manager/modules/restapi/model/s...

In that interface you will need to add a sub-interface representing the action:

interface Paint { }

The JAX-RS interface will be generated from that. Currently these sub-interfaces are empty. In the future they will contain the specifications of the parameters (currently in the rsdl_metadata.yml file).

These changes will currently affect only the specification of the RESTAPI, not the implementation, so in in the "Backend*Resource" classes things won't change yet.

Currently I do not really understand where we are going here. Are we trying to get rid of rdsl? So basically two questions: 1) What is the final goal? 2) What speaks agains using Hibernate validator on Daos in combination with JAX-RS annotated resources (and just removing all interfaces, as far as I can see we only have one implementation per endpoint) and creating all schemas and clients through SWAGGER tooling?

If you have doubts, please let me know.

Regards, Juan Hernandez

-- Dirección Comercial: C/Jose Bardasano Baos, 9, Edif. Gorbea 3, planta 3ºD, 28016 Madrid, Spain Inscrita en el Reg. Mercantil de Madrid – C.I.F. B82657941 - Red Hat S.L. _______________________________________________ Devel mailing list Devel@ovirt.org http://lists.ovirt.org/mailman/listinfo/devel

Thanks, Roman