I’ve a question for all you gurues here!
I’ve noticed RAML Spec 1.0 (RC2) has amazing “extensions” capabilities around a Raml Type, including:
- Modularization (thru #RAML 1.0 extension or #RAML 1.0 overlays),
- The required/optional facet on ObjectType,
- The “additionalProperties” facet on ObjectType,
- Multiheritance and union types,
- User-defined Facets…
So, there is a lot of posibilities to “increase” the length or structure of any type. That’s incredibly usefull, of course. But, what if we need to “decrease” the structure or length of any type… How can we reach such goal?
The use case that justifies this need is described as following:
Coming from the world of strongly typed languages, I’m used to thinking in terms of interfaces, abstract classes, inheritance, aggregation and composition, so, considering such flexibility offered by the RAML 1.0 specification, I always feel tempted to declare flexible or polymorphic types, using multi-inheritance and union. When it’s used togheter with RAML Extension and Overlays (and some other cool features mentioned above), I have always been able to “extend” functionality. The major problem comes when I want to “decrease” funcionality.
For example: Consider we want to use RAML types in order to maintain a complete set of business entities that conform a canonical model of data. It is reasonable to think that an entity, conceptually speaking, is the same in independence of which facet of certain functionality is used. But, when attempting to use that entity as part of a functionality exposed in an API, it may not be required to use ALL the attributes of that entity, but only a portion of them (without losing sight of the fact that not using all attributes within such functionality, do not mean that they do not make sense as part of the aforementioned entity).
So, if we want to use a portion of an entity as income for a POST method invokation of any endpoint, it could be desirable to use the same entity, with a different subset of attributes, when invoking a GET method for the same (or even other) endpoint.
So, in conclusion… there is a way to adapt the structure of a RAML Type conveniently according to it use inside the entire API, that is:
- Declaring a “entity-base” that can mutate if it’s used in income body for a POST or as outcome body for a GET, for example?.
- There is an elegant way to declare a complete set of attributes for a type, but cutting the non-used attributes for a specific used inside de API?.
- If it were not possible, would there be a way to “extend” the functionality of a base type, without declaring ‘n’ child entities, one for each possible use within the API?