I'd like to pause this discussion for a brief moment, and advise that we
watch this APIGee video.
http://www.youtube.com/watch?feature=player_embedded&v=QpAhXa12xvU

This is something that Erin pointed us to early on, and serves as a basis
for a good RESTful architecture. There are too many good points made that
will allow our API to scale and be intuitive for other developers.

It's very important that we are on the same page. I believe a lot of
"format" questions will be answered by following the APIGee guidelines.

- Mike


On Sun, Sep 15, 2013 at 6:30 PM, Chris Geer <chris@cxtsoftware.com> wrote:

> Since we've been having a lot of discussions on data structures lately I
> wanted to write down what my suggestions were. These aren't 100% complete
> examples but show the relationships
>
> CRUD Interfaces
>
> Page (/pages/<page-id>)
> {
>   id: <id>,
>   owner: <owner>,
>   regionIds: [
>     <id>, <id>, <id>   (region order is based on order in list, not field
> on region object)
>   ]
> }
>
> Region (/pages/<page-id>/regions/<region-id>
> {
>   id: <id>,
>   regionWidgetIds: [
>     <id>, <id>, <id>   (widget order is based on order in list, not field
> on region widget object)
>   ]
> }
>
> Region Widget
> (/pages/<page-id>/regions/<region-id>/regionwidgets/<region-widget-id>
> {
>   id: <id>,
>   widgetId: <widgetId>,
>   collapsed: <collapsed>,
>   ...
> }
>
> Region Widget
> Properties
> (/pages/<page-id>/regions/<region-id>/regionwidgets/<region-widget-id/properties/<propertyId>)
> {
>   ....
> }
>
> Widget (/widgets/<widget-id>
> {
>   id: <id>
>   title: <title>
> }
>
>
> Render Interface (custom mime-type) (Read Only)
>
> /pages/<page-id>
> {
>   id: <id>,
>   regions: [
>     {
>       id: <id>,
>       regionWidgets: [
>         {
>           id: <id>,
>           widgetId: <widgetId>,
>           title: <title>,
>           properties: [
>             {
>                key: <key>,
>                value: <value>
>              }
>           ]
>         }
>       ]
>     }
>   ]
> }
>
> You should also be able to render sub elements below a page so for example,
>
> /pages/<page-id>/regions/<region-id> with the custom mime-type would render
> a single region.
>
>
> Obviously there is still room for uncertainty in some places. For example,
> what happens if your have a region with three region widgets then you save
> the region but only include two ids in the list? Personally, I think that
> should delete the missing regionWidget because that list denotes ordering.
> The reason I don't like an "order" attribute on the sub objects is that
> what if you save two sub objects with the same order (which would happen if
> you ever wanted to swap two objects in order because you have to update
> them then save each one so they would have the same order at least
> momentarily on the server)?
>
> Anyway, my 2-cents.
>
> Chris
>