search

restful-api-description-language / RADL

RADL: A description language and tooling for hypermedia-driven RESTful APIs
Apache License 2.0
23 stars 5 forks source link

Generate data transfer objects for property groups #9

Closed RaySinnema closed 9 years ago

RaySinnema commented 9 years ago

From @ApiSecRay on March 27, 2015 12:1

Copied from original issue: restful-api-description-language/radl-java#1

jonathanrobie commented 9 years ago

I assume that our use cases for data models are almost always JSON?

Spring Data seems to have support for JSON Schema (http://spring.io/blog/2015/03/26/what-s-new-in-spring-data-fowler). Could we get rid of data models by adding support for an external data schema specified using JSON Schema?

RaySinnema commented 9 years ago

Our media types (not data models) will most often be JSON-based, but we also want to support XML-based and other formats.

We also want to support non-Java technologies and non-Spring Java technologies, like JAX-RS, so whatever we decide should work outside a Spring-based environment as well.

gentlewind commented 9 years ago

Some terms turn to be a bit more confusing today. Data models, resource models, representations, etc. What are these different with each other? I assume that data model in RADL is not revelant to any particular message formats. Is this right?

julian-hj commented 9 years ago

A good first step would be to support data-model in the doc generation. I guess the other tooling stages could be helpful in some cases, but they seem less critical.

The main attraction I see for data-model is that it gives us a way to document the data returned by self-describing media types, where the media type is just a generic protocol and the eventual object will include a type link. And it does it in a way that could be directly converted into HTML documentation, instead of just including a link to some external resource (which is pretty unhelpful for the API consumer).