Modelling variety of attributes for resources

[Mateusz Loskot]

Hi,

I'm quite new to designing resources and representations for Web APIs.
One if things I'm struggling a bit is modelling variety of attributes
of items in a collection.
For instance, `/products`, then `/products/1` and `/products/2` share
common set of attributes (e.g. name, description), but they also have
set of attributes specific (e.g. depending on category of product).
IOW, it models a typical OO hierarchy.

Can anyone recommend a good resource devoted to modelling/encoding
attributes set for resource representations?

One of the recommendations I've found is Darrel Miller talk at NDC
https://vimeo.com/131643022 where from around 27min and 29min
suggests to "avoid structure, that's good". That means a flat list of
attributes has advantages, but it is not entirely clear to me what
exactly. Darrel mentions that adding things is easy, removing things
is hard, but I see little difference between adding/removing one
attribute vs whole group./

Then later, from around 22:18, Darrel discusses attribute groups and
among number of reasons why to group attributes,
one is particularly interesting: optional attributes - if group is
present, then attributes of that group are mandatory.
That actually is a compelling reason to use groups - I see it can be
useful to model hierarchies of categories and subtypes for
items in resources.

I'm interested to hear any ideas related to modelling attributes for resources.

Best regards,
--
Mateusz Loskot, http://mateusz.loskot.net

[Andrew B]

We have several APIs that pull back polymorphic sets in a pretty straightforward way, e.g.:

GET /products

[

  {

    "type": "rope",

    "unitLength": 30

  },

  {

    "type": "nails",

    "packQuantity": 250

  }

]

[Mateusz Loskot]

Yes, I've eventually come to similar form.
Next, I started considering how to define it in RAML,
http://forums.raml.org/t/modelling-data-type-with-variety-of-attributes/1485

Do you define your types using RAML or JSON Schemas perhaps?

Mateusz

> --
> You received this message because you are subscribed to the Google Groups
> "API Craft" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to api-craft+...@googlegroups.com.
> Visit this group at https://groups.google.com/group/api-craft.
> For more options, visit https://groups.google.com/d/optout.

[Andrew Braae]

We use RAML, with embedded json schema to describe the actual request/response. An example array definition (from http://stackoverflow.com/a/10812312) is:

"items": {
  "type": [
     {"type":"object", "properties": {"a": {"type": "object", "properties": {"ax": { "type":"number"}}}}},
     {"type":"object", "properties": {"b": {"type": "object", "properties": {"bx": { "type":"number"}}}}},
     {"type":"object", "properties": {"c": {"type": "object", "properties": {"cx": { "type":"number"}}}}}
  ]
}

The new RAML 1.0 adds extra support for types right inside the RAML but AFAIK you still need to fall back to json schema for this kind of thing.

Last time we looked the Open API (Swagger and pals) guys have opted not to support any such complex modelling, which is a real shame, so we stuck with RAML.

You received this message because you are subscribed to a topic in the Google Groups "API Craft" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/api-craft/geUAKGa1EuY/unsubscribe.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.

[Mateusz Loskot]

Interesting ideas, indeed.
Thanks Andrew
Mateusz