[openstack-dev] [ara] Best practices on what to return from REST API ?

Chris Dent cdent+os at anticdent.org
Wed Aug 9 14:02:29 UTC 2017

On Wed, 9 Aug 2017, David Moreau Simard wrote:

> So I'm making what I think is good progress towards the python and
> REST API implementation for ARA but now I have a question.
> I've made the following API "GET" endpoints:

If people remember to actually read this and respond, you'll likely get
as many different responses to this as there are options.

Alot of it is preference, but you've mentioned that you are trying
to optimize for scale and concurrency so I think there are some things
you can do to maintain a reasonable grammar, hew to standards (both
real and the dreaded "best practice"), keep things simple, and be
fast (in aggregate). You've overcome the most important hurdle
already by enumerating your resources (as nouns):

> - files (saved Ansible files)
> - hosts (hosts involved in playbooks and their facts, if available)
> - playbooks (data about the actual playbook and ansible parameters)
> - plays (data about plays)
> - results (actual results like 'ok', 'changed' as well as the data
> from the Ansible module output)
> - tasks (data about the task, like name, action and file path)

>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

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
- 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

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.

Chris Dent                      (⊙_⊙')         https://anticdent.org/
freenode: cdent                                         tw: @anticdent

More information about the OpenStack-dev mailing list