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

Rename <data-model > to <message> #31

Closed RaySinnema closed 9 years ago

RaySinnema commented 9 years ago

I fear that the term data-model may confuse some people. They are not about persistent data storage, or even about domain objects, but they describe what the messages look like that are sent over the wire. To make that clearer, we should rename <data-model> to <message>.

jonathanrobie commented 9 years ago

A data model is not the same thing as a message, it is just one of the things that a message represents. Also, a message is a representation, a data model is abstract and can be represented by multiple media types. I think renaming the element to message is more confusing than the status quo.

RaySinnema commented 9 years ago

How about naming it properties? We'd have to do some schema fu to make sure things like examples are only valid on the top-level properties. Note that this is a breaking change.

jonathanrobie commented 9 years ago

I think that would be helpful. One of the reasons data-model is confusing is that it's not at all clear how it is related to properties, and why we need both.

gentlewind commented 9 years ago

＋1. properties is more close to its mission.

RaySinnema commented 9 years ago

But what do we call the wrapper around all the various properties elements, i.e. what is now called data-models?

jonathanrobie commented 9 years ago

See https://github.com/restful-api-description-language/RADL/issues/34

RaySinnema commented 9 years ago

OK, "message" is really not a good term. I was trying to remove any confusion with "data" as "stored in a database" and tried to emphasize that we're talking about information exchanged between client and server. But "message" suggests something that goes over the wire as an actual HTTP body, which is not what I meant either. We're trying to capture the abstract structure of the information that is exchanged, with "abstract" meaning the informational value rather than the concrete serialization in a media type.