Bugzilla (bugzilla.redhat.com) will be under maintenance for infrastructure upgrades and will not be unavailable on July 31st between 12:30 AM - 05:30 AM UTC. We appreciate your understanding and patience. You can follow status.redhat.com for details.
Bug 818674 - [REST API] Use of "uuid" is non-standard - we should consistently use "id" when referring to a unique, unchangeable identifier for an item
Summary: [REST API] Use of "uuid" is non-standard - we should consistently use "id" wh...
Alias: None
Product: OKD
Classification: Red Hat
Component: Pod
Version: 1.x
Hardware: Unspecified
OS: Unspecified
Target Milestone: ---
: ---
Assignee: Krishna Raman
QA Contact: libra bugs
Depends On:
TreeView+ depends on / blocked
Reported: 2012-05-03 17:39 UTC by Clayton Coleman
Modified: 2014-06-18 07:25 UTC (History)
3 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Last Closed: 2012-05-05 02:33:19 UTC
Target Upstream Version:

Attachments (Terms of Use)

Description Clayton Coleman 2012-05-03 17:39:45 UTC
The majority of REST APIs use the attribute name "id" to refer to the unique identifier for a field that is invariant, as well as a lot of automatic infrastructure in systems.

To reduce growing pains and ease client use, whenever we expose a unique identifier field that is invariant across time we should use 'id' instead of 'uuid'.  Domain_id is already this way on the same line of reasoning (because domain names are fairly stable and the logical arguments for them being changeable make sense).

  Gear instance (id is appropriate)
  Gear group (does this have a distinct group id?)
  Cartridge type (id is more suitable than name)
  Cartridge instance (id is appropriate, with type_id referencing the original type)

I'm a bit concerned about the Cartridge type object using 'name', which almost always means "the name of this object as presented to a user".  "ha-proxy-1.4" is an identifier string, not a user displayable name like "High Availability Proxy 1.4".  Over the lifetime of ha-proxy-1.4, the id will remain constant (a new cartridge ha-proxy-1.5 is a new cart, not the same old cart).  The value on the cartridge instance would be consistent.  When a user calling the rest api wants to show the list of cartridge types to a user, getting back 

  {:id => 'ha-proxy-1.4', :name => 'High Availability Proxy 1.4'} 

feels much more consistent with other resources than:

  {:name => 'ha-proxy-1.4', :display_name => 'High Availability Proxy 1.4"}

(since I would call Application.name to get a display name for an app, but CartridgeType.display_name to get the display name for a cart).  

However, given that a specific cartridge instance inside an application may have its own unique id (cart instance vs. cart type) I understand that you read the cart resource from /cartridges and then post it to an app, which feels fairly natural.  Maybe the problem is that "type" is really what a cartridge should have (standalone/embedded is less relevant).  Possibly what would make most sense in the long run is:

  {:type => 'ha-proxy-1.4', :name => 'High Availability Proxy 1.4', :arity => '0..1'}

POST /domains/id/applications/id/cartridges.json
  body {:type => 'ha-proxy-1.4', :name => 'High Availability Proxy 1.4', :arity => '0..1'}
  resp {:id => 'uuid', :type => 'ha-proxy-1.4', :name => 'High Availability Proxy 1.4'}

Comment 1 Krishna Raman 2012-05-04 20:17:57 UTC
Converted to use-case https://rally1.rallydev.com/#/4670255914d/detail/userstory/6271766484

Note You need to log in before you can comment on or make changes to this bug.