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

On 10/26/2015 04:56 PM, Roman Mohr wrote: The motivation for this change is that currently we don't have a central place where the RESTAPI is specified, rather we have several different places, using several different technologies: * XML schema for the data model. * JAX-RS for part of the operational model (without the parameters). * rsdl_metadata.yaml for the parameters of the operational model. This makes it difficult to infer information about the model. For example, the generators of the SDKs have to download the XML schema, and the RSDL (which is generated from the JAX-RS interfaces using reflection and combining it with the information from the rsdl_metadata.yaml file) and then they have to do their own computations to extract what they need. Same happens with the CLI: it has to extract the information it needs from the Python code generated for the Python SDK, yet another level of indirection. We are also lacking a comprehensive reference documentation of the RESTAPI. What we currently have has been written by hand, and gets out of sync very quickly, and we don't even notice. To solve these issues I intend to have the specification of the RESTAPI only in one place, and using only one technology. I decided to use Java interfaces for that. Note however that they are just the support for the information, like paper is the support for ink. I decided to use Java because it is easy to create, modify and re-factor using tools familiar to most of us. These source of these interfaces is analysed (using QDox, currently) and a "model" of the RESTAPI is generated in memory. This model is independent of the supporting Java source, and easy to consume. For example, imagine that you want to list all the types available in the model and for each one display its documentation: Model model = ...; for (Type type : model.getTypes()) { Name name = type.getName(); String doc = type.getDoc(); System.out.println(name + ": " + doc); } Something like this, but more elaborate, will be part of a web application that provides comprehensive reference documentation, assuming that we dedicate the time to write documentation comments in the specification. I intend to use this model also to do simplify the generators of the SDKs and the CLI. In addition these are some of the things that I would like to change in the near future (for 4.0): * Move the specification of the parameters of operations out of the rsdl_metadata.yaml file and into the model. For example: @Service public VmService { /** * The operation to add a virtual machine. */ interface Add { /** * The representation of the virtual machine is received * as parameter, and the representation of the created * virtual machine is returned as result. */ @In @Out Vm vm(); /** * In the future, we will be able to specify other * parameters here. */ @In Boolean force(); /** * Even with default values. */ @In default Boolean force() { return true; } /** * And we will be able to specify constraints, which * will replace the rsdl_metadata.yaml file. */ @Constraint default boolean vmNameMustNotBeNull() { return vm().name() != null; } } } * Enforce the constraints automatically. If the constraints are in the model, then we can just check them and reject requests before delivering them to the application. Currently we do this manually (and often forget) with calls to "validate(...)" methods. * Generate the Java classes directly from the model. Instead of Model -> XML Schema -> Java, we can do Model -> Java. This will allow us to solve some of the XJC compiler limitations, like the horrible way we handle arrays today. * Replace JAX-RS with a simpler infrastructure that supports better streaming and CDI injection. * Add support for multiple versions of the API, using the "Version" header, and generating different Java classes for entities and services. For example, if we have versions 4 and 5 of the model as separate artifacts, then we can generate "V4Vm" and "V5Vm" entity classes, and "V4VmService" and "V5VmService" service classes. These can be used simultaneously in the server, so we can have in the same engine implementations for multiple versions. The final picture isn't completely defined yet. 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.