Modelling data type with variety of attributes



I’m modelling a resource, collection and member, where each members may have different set of data attributes.

In terms of object-oriented model, it is a very basic hierarchy with two levels: base type and subtypes. Another angle to view it is that members can have dynamic schemas.

I know inheritance is no stranger for RAML and for REST APIs in general,so object-oriented approach (OO) is possible. However, I’m not entirely convinced such object-orientation is necessary at all,especially from the API consumer perspective - representations.

Basically, the data model is this:

  • collection of daily activities
  • each acvitivy is described with common set of attributes and attributes specific to actual type of the activity
  • OO model would be something like this:
activity <---|--- reading
             |--- cooking
             |--- driving
             |--- running
             |--- swimming
             ... <tens or hundreds of types of activities>

Here is example of GET response with collection of activities:

GET /me/activities

  "activities": [
      "type": "running",
      "startTime": "2015-01-01T10:00:00Z",
      "endTime": "2015-01-01T11:00:00Z",
      "location": "Park ABC",
      "running": {
        "avgPace": 6.5,
        "shoes": "xyz"
      "type": "cooking",
      "startTime": "2015-01-01T16:00:00Z",
      "endTime": "2015-01-01T16:30:00Z",
      "location": "Home",
      "cooking": {
        "meal": "dinner",
        "recipeName": "My Favourite Roast",
        "recipeSteps": []
        "incredients": []
  1. What options do I have to capture such data model in RAML?

  2. Do I indeed go for the OO approach and define RAML Data Types with base Activity, then Cooking, Running,…and possibly long list of types?

  3. Do I define just one data type, Activity, with the common set of attributes and the additional "<activity name>" with type: object, then, at RAML level, I just assume the schema of activity-specifig attributes is free and dynamic? Response/Request examples would have those specified though, but I think I might expect problems e.g. with mock services generated based on RAML.

I’ve asked similar, but general, not RAML, question on API Craft group.
I’ve also discussed it briefely with friendly folks on the Slack HTTP APIs channel where I received suggestions that, from API user perspective, no OO and inheritance is necessary, though server-side implementation might benefit form that approach.

Regardless, here I’m asking specifically about RAML best practices.

Having little REST design experience, I’ll appreciate any feedback.



Aha! I’ve been reading the RAML 1.0 spec more carefully and I found answer to the technical aspects my questions: how to handle additional properties in RAML Data Types. It is described in the spec very well. Sweet!

Still, I’d like to learn about the OO approach for resources modelling though.