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...
Keywords:
Status: CLOSED UPSTREAM
Alias: None
Product: OKD
Classification: Red Hat
Component: Pod
Version: 1.x
Hardware: Unspecified
OS: Unspecified
high
medium
Target Milestone: ---
: ---
Assignee: Krishna Raman
QA Contact: libra bugs
URL:
Whiteboard:
Depends On:
Blocks:
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:
Environment:
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).

Affected:
  Application
  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:

/cartridges.json
  {: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.