Hi, I'm all for strong typing the stuff we send out and receive. As for automatic generation, same can be applied by the swagger-codegen, which generates from our documented swagger-annotations the client-code. So it works in a reversed way, from our Java-code to JSON, like the following: "MetricParams" : { "id" : "MetricParams", "description" : "Metric definition model", "properties" : { "name" : { "type" : "string" }, "tags" : { "$ref" : "Map[string,string]" }, "dataRetention" : { "type" : "integer", "format" : "int32", "description" : "Overrides the data retention setting at the tenant level" } } }, And swagger-codegen understands that. - Micke ----- Original Message ----- From: "John Mazzitelli" <mazz(a)redhat.com&gt; To: hawkular-dev(a)lists.jboss.org Sent: Thursday, 26 February, 2015 9:47:06 PM Subject: [Hawkular-dev] generation of message POJOs via JSON schema There is this really nice maven plugin that takes JSON schema and generates Java POJOs annotated with GSON annotations. I took this stuff and created a sample module in the bus repo and see how it works. It works very nicely and I think we can use this very easily in our stuff. First, here is a site that discusses JSON schema if you aren't familiar (its essentially like XML Schema only for JSON): http://json-schema.org/documentation.html We can use this maven plugin to generate an API that our Java components can use to talk to each other. To see what the generated code looks like with any JSON schema, here's a play area where you can see it in realtime: http://www.jsonschema2pojo.org/ Here's what my sample JSON schema looks like (you'll see it uses primitives as well as sets/lists and embedded types (see address type) and a set of embedded types (see phoneNumbers): https://github.com/hawkular/hawkular-bus/blob/master/hawkular-bus-samples... Here is where my test code creates the message via the POJO API that was generated by the maven plugin: https://github.com/hawkular/hawkular-bus/blob/master/hawkular-bus-samples... If we use this stuff, we write the JSON schema which automatically provides documentation that non-Java clients can use to know what the clients need to send/consume, or they can use the schema themselves to generate their own client code. We use the schema internally to generate Java POJOs that we then use in our Java components (like what my sample code demonstrates). Here is what the maven plugin usage looks like - its pretty simple: https://github.com/hawkular/hawkular-bus/blob/master/hawkular-bus-samples... _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

Hello, Very seldom REST API's come with schemas; the typical workflow when working with REST: 1) read documentation about the rest end-point 2) if the project has a test site, try a few live queries 3) Write application code (TDD or not) 3.1) if something is wrong with the request, the service will return an error; read the documentation again 3.2) if something is wrong with the reply (not what expected), then read the documentation again 4) Add plenty of integration tests This workflow gets simplified if the project provides an SDK for integration; but not by a lot, there is still documentation to be read, tests, errors, etc. Because of JSON's ease of use and the possibility of implementing the client in many languages/frameworks, the schemas are no longer relevant. Good documentation (with examples), good REST API design, good errors, a live test tool, and an SDK are far more important. Here are a few samples on how Google, Facebook, Twitter, ans AWS approach this: 1) Documentation: https://developers.facebook.com/docs/graph-api/reference/v2.2/album/photos 2) Documentation: https://developers.google.com/accounts/docs/OAuth2WebServer 3) Test Tool: https://developers.google.com/apis-explorer/#p/blogger/v3/blogger.blogs.g... 4) Documentation: https://dev.twitter.com/rest/reference/get/statuses/home_timeline 5) SDK: http://aws.amazon.com/sdk-for-python/ With all this being said, here is how I would see using these tools in Hawkular: 1) Do all the work in the individual projects (write classes; annotated classes if necessary). 2) Use a tool to generate schemas from code 3) Make the schemas definitions part of the documentation or SDK I like the concepts from swagger tool that Micke talked about because you can drive the schema generation from the code. Now if we find a tool that is bi-directional, that's even better. The users and community members could then use the schemas to generate our code for their own applications to interact with Hawkular. Now, one thing that I would be very concerned to see is transforming the bus into a central repository and source for schemas. The bus should be designed following the "dumb pipes" [1] principle. It should take care of delivery but never ever inspect or make decisions based on actual content piped. [1] http://martinfowler.com/articles/microservices.html#SmartEndpointsAndDumb... Thank you, Stefan ----- Original Message -----

On Friday, February 27, 2015 13:46:05 Jay Shaughnessy wrote: +100 The schema, after all is a sort of documentation. If it is "functionally" tied with the implementation itself (i.e. one generated from the other) then it also never gets out of sync, unlike the written documentation.

I found writing the schema and generating the code to be fairly painless. But I'll look into the swagger stuff - does anyone have links for examples on how to use its maven plugin to take code and generate json schema from it? What annotations does it use? ----- Original Message -----

Hello, I hit this issue so I'd like to 'reopen' the topic. What about introducing a new repo only schemas and swagger docs. Not to mix it with the bus (dumb pipes principle). Currently the swagger is auto-pushed here https://github.com/hawkular/hawkular.github.io/tree/swagger and I think it's not perfect. We need some shared API/serialization contract. The minimum is having it for the msg format. However message is often composed of concrete entities, arrays of entities, etc. We can go further and leverage the fact of composability. If we have schema for X it's easy to derive the schema for List<X>. I think each component should be autonomous enough and have right to define its own entity classes, but why to repeat all the time definition of, say, the resource? If there is an agreement how resource should look like, we can define it in the schema (possibly with a version). Is 1 json message something like DTO (ad-hoc format, almost no patterns) or rather set of smaller well-defined "sub-messages" (possibly entities)? Of course, I am not talking about those stupid messages with something like "{ "result": 12 }". wdyt? ----- Original Message ----- | From: "Stefan Negrea" <snegrea(a)redhat.com&gt; | To: "John Mazzitelli" <mazz(a)redhat.com&gt; | Cc: hawkular-dev(a)lists.jboss.org | Sent: Friday, February 27, 2015 7:28:25 PM | Subject: Re: [Hawkular-dev] generation of message POJOs via JSON schema | | Hello, | | Very seldom REST API's come with schemas; the typical workflow when working | with REST: | 1) read documentation about the rest end-point | 2) if the project has a test site, try a few live queries | 3) Write application code (TDD or not) | 3.1) if something is wrong with the request, the service will return an | error; read the documentation again | 3.2) if something is wrong with the reply (not what expected), then read the | documentation again | 4) Add plenty of integration tests | | This workflow gets simplified if the project provides an SDK for integration; | but not by a lot, there is still documentation to be read, tests, errors, | etc. | | Because of JSON's ease of use and the possibility of implementing the client | in many languages/frameworks, the schemas are no longer relevant. Good | documentation (with examples), good REST API design, good errors, a live | test tool, and an SDK are far more important. | | Here are a few samples on how Google, Facebook, Twitter, ans AWS approach | this: | 1) Documentation: | https://developers.facebook.com/docs/graph-api/reference/v2.2/album/photos | 2) Documentation: https://developers.google.com/accounts/docs/OAuth2WebServer | 3) Test Tool: | https://developers.google.com/apis-explorer/#p/blogger/v3/blogger.blogs.g... | 4) Documentation: | https://dev.twitter.com/rest/reference/get/statuses/home_timeline | 5) SDK: http://aws.amazon.com/sdk-for-python/ | | With all this being said, here is how I would see using these tools in | Hawkular: | 1) Do all the work in the individual projects (write classes; annotated | classes if necessary). | 2) Use a tool to generate schemas from code | 3) Make the schemas definitions part of the documentation or SDK | | | I like the concepts from swagger tool that Micke talked about because you can | drive the schema generation from the code. Now if we find a tool that is | bi-directional, that's even better. The users and community members could | then use the schemas to generate our code for their own applications to | interact with Hawkular. | | | Now, one thing that I would be very concerned to see is transforming the bus | into a central repository and source for schemas. The bus should be designed | following the "dumb pipes" [1] principle. It should take care of delivery | but never ever inspect or make decisions based on actual content piped. | | [1] | http://martinfowler.com/articles/microservices.html#SmartEndpointsAndDumb... | | | | Thank you, | Stefan | | | ----- Original Message ----- | > From: "John Mazzitelli" <mazz(a)redhat.com&gt; | > To: hawkular-dev(a)lists.jboss.org | > Sent: Thursday, February 26, 2015 3:35:52 PM | > Subject: Re: [Hawkular-dev] generation of message POJOs via JSON schema | > | > Here's an example PR that can show where we can build this "glue code": | > | > https://github.com/hawkular/hawkular/pull/31 | > | > It's a JSON schema with generated POJOs. In this case, it is just the | > metrics. Stefan mentioned he'd rather the metrics provide this - which is | > fine, we don't have to merge this PR - we just do something similar in the | > metrics repo rather than in the hawkular project itself. | > | > But the point is, this shows how we can produce a small jar with just the | > JSON schema files and the Java classes that represent those JSON objects. | > These generated POJOs play nice with the bus infrastructure and the API we | > are using to produce/consume messages. | > _______________________________________________ | > hawkular-dev mailing list | > hawkular-dev(a)lists.jboss.org | > https://lists.jboss.org/mailman/listinfo/hawkular-dev | > | _______________________________________________ | hawkular-dev mailing list | hawkular-dev(a)lists.jboss.org | https://lists.jboss.org/mailman/listinfo/hawkular-dev |