Open Stack

On Wed, Aug 9, 2017 at 10:02 AM, Chris Dent <cdent+os at anticdent.org> wrote:
>
> If people remember to actually read this and respond, you'll likely get
> as many different responses to this as there are options.
>

I expected as much but I very much appreciate your reply regardless!
\o/

>
> From there rather than /{collection} for list and
> /{collection}?id={id} for single entity I'd do:
>
>     /{collection}     # list
>     /{collection}?filter=to_smaller_list # e.g. playbook_id
>     /{collection}/id  # single entity
>

That makes sense.

>
> In the collection response only include the bare minimum of data, in
> the single entity include:
>
> - whatever is thought of the entity
> - anything that you think of as a child, represent as links
>   elsewhere
> - it is makes sense to have /{collection}/id/{child} and {child} is
>   actually some other /{collection}/id, consider making the child
>   URI a redirect (that is /{collection/id/{child} redirects to
>   /{childtype}/{child id}
> - if a child is actually children then you'll want to adjust the
>   grammar somewhat: /{collection}/id/{child collection}/id
>

I've read about HATEOAS [1] and it's something I will likely implement.
So, if I'm understanding correctly, you would perhaps only include
references to the childs but not their actual data ?

With the concept of HATEOAS, it would go something like:
# Example task
{
    "id": 8,
    "links": [
        {
            "href": "/api/v1/tasks/8",
            "rel": "self"
        }
    ],
    "name": "Ansible >=2.2: include_role tasks",
    "playbook_id": 5,
    "results": [
        {
            "href": "/api/v1/results/1", # or /api/v1/tasks/8/results/1
            "rel": "1"
        },
        {
            "href": "/api/v1/results/2",
            "rel": "2"
        },
        # ...
    ]
}

I think that would be manageable and it wasn't something I had considered.

> This provides you with good urls for things, straightforward ways of
> getting at data, and the capacity to spawn off concurrent requests
> in response to an initial query.
>
> This is essentially the same as your option 2, but with more
> structure to the URLs.

Thanks for the input !

[1]: https://spring.io/understanding/HATEOAS

David Moreau Simard
Senior Software Engineer | OpenStack RDO

dmsimard = [irc, github, twitter]