[ovirt-devel] [ATN] Introduction of RESTAPI metamodel

[Juan Hernández]

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

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/src/main/java/types/Vm.java

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/src/main/java/services/VmService.java

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.

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.