Inconsistent meaning of flavor_ref in requests vs. responses

[Shaunak Kashyap]

In the "Create service" API (POST /services), the "flavor_ref" property is used to indicate a flavor ID (e.g. "asia"), not a flavor href (e.g. "http://192.168.59.103:81/v1.0/flavors/asia").

In the "Get service" API (GET /services/{service_id}), the "flavor_ref" property is used to indicate a flavor href, not a flavor ID.

This inconsistency will make things difficult for consumers of the API (such as SDKs and other client code) since such software often uses a common model for serializing request representations and deserializing response representations.

My suggestion would be:
* to use "flavor_id" (instead of "flavor_ref") to indicate flavor IDs in request and response representations of all resources that require/return flavors, and
* to add a new link with rel = "flavor" and href = "<flavor resource URL>" (e.g. "http://192.168.59.103:81/v1.0/flavors/asia") in response representations of all resources that return flavors.

[Amit Gandhi (amit-gandhi)]

I would like to get the API-WG take on this item. Should flavors be referred to by their ID's, and contain a link in the links section to it. Or should it be referred to by flavor_ref which is always an href to follow.

[Shaunak Kashyap (ycombinator-o)]

I have posted this as a question to the API-WG on the openstack-dev@ mailing list: http://lists.openstack.org/pipermail/openstack-dev/2014-November/050798.html

[Shaunak Kashyap (ycombinator-o)]

There hasn't been any activity on the mailing list thread for the past couple of days now. Based on the discussion there, I would suggest using "flavor_id" (instead of "flavor_ref") to indicate bare flavor IDs (e.g. "asia") in request and response representations of all resources that require/return flavors . Thoughts?

[Amit Gandhi (amit-gandhi)]

yes. I would recommend "flavor_id" in the normal section, and then have a link in the links section with a "rel" = "flavor_ref" so that users can still follow the link to get flavor information.

[Shaunak Kashyap (ycombinator-o)]

Nit: should it be "rel" = "flavor_ref", or "rel" = "flavor" (because all links are refs)?

[Malini Kamalambal (malini-pk)]

In terms of making the API user friendly, I agree with Shaunak's suggestion - though my vote is to simply use flavor instead of flavor_id and link in the links section with a "rel" = "flavor_ref"

But this will make us inconsistent with some of the Openstak APIs (not a big deal IMO, since there seems to be no consistency across APIs as is - unfortunately!! ).

1. Per Compute V2 API http://developer.openstack.org/api-ref-compute-v2.html
'flavorRef plain csapi:string
The flavor reference for the desired flavor for your server instance.

2. Per DB API http://developer.openstack.org/api-ref-databases-v1.html

'flavorRef plain xsd:string
Reference (href) to a flavor as specified in the response from the list Flavors API call. This is the actual URI as specified by the href field in the link.

Rather than the flavor URI, you can also pass the flavor id (integer) as the value for flavorRef. For example, the flavor id for the flavor URI shown above is "1".'

[Shaunak Kashyap (ycombinator-o)]

I would recommend naming the bare ID property as "flavor_id", instead of "flavor". This way, in the future if you decide to compose a flavor's representation inside another resource's representation, you can name _that_ property "flavor". That said, I realize this is veering towards the bikeshed so I'm happy to go with either right now :)

[Shaunak Kashyap (ycombinator-o)]

To make things a bit more concrete, here's what I'm proposing for flavor references in other resources' representations:

When referencing a flavor in another resource's REQUEST representation:

{
  "flavor_id": "asia",
  // ... other resource properties
}

When referencing a flavor in another resource's RESPONSE representation:

{
  "flavor_id": "asia",
  "links": [
    {
      "rel": "flavor",
      "href": "{base_uri}/flavors/asia"
    }
  ],
  // ... other resource properties
}

Please let me know if this is acceptable and I'll send in a patch with the necessary changes.

[Amit Gandhi (amit-gandhi)]

Addressed by https://review.openstack.org/#/c/138674/

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/138674
Committed: https://git.openstack.org/cgit/stackforge/poppy/commit/?id=b3bc5f6c321f847533cfd9349d9327889fe89b9c
Submitter: Jenkins
Branch: master

commit b3bc5f6c321f847533cfd9349d9327889fe89b9c
Author: Shaunak Kashyap <email address hidden>
Date: Wed Dec 3 01:48:52 2014 -0800

    flavor_ref -> flavor_id

    Change-Id: I3578f906ddec69b062d18c9d37a8b764df067602
    Closes-Bug: 1392573