From 0b1f0710b7f3b70e1549369da3d25f2f665e68ba Mon Sep 17 00:00:00 2001 From: Ian Booth Date: Tue, 15 Sep 2015 13:43:37 +1000 Subject: [PATCH 1/3] Add API doc for supported series --- docs/API.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 75 insertions(+), 5 deletions(-) diff --git a/docs/API.md b/docs/API.md index 121bf4c2b..65cb195db 100644 --- a/docs/API.md +++ b/docs/API.md @@ -425,6 +425,7 @@ Example: `GET /meta` "promulgated", "revision-info", "stats", + "supported-series", "tags" ] ``` @@ -578,6 +579,7 @@ Example: `GET foo/meta` "promulgated", "revision-info", "stats", + "supported-series", "tags" ] ``` @@ -696,9 +698,10 @@ type CharmMetadata struct { Subordinate bool `json:",omitempty"` // Provides and Requires map from the relation name to // information about the relation. - Provides map[string]Relation `json:",omitempty"` - Requires map[string]Relation `json:",omitempty"` - Peers map[string]Relation `json:",omitempty"` + Provides map[string]Relation `json:",omitempty"` + Requires map[string]Relation `json:",omitempty"` + Peers map[string]Relation `json:",omitempty"` + SupportedSeries []string `json:",omitempty"` Tags []string `json:",omitempty"` } @@ -746,6 +749,10 @@ Example: `GET wordpress/meta/charm-metadata` "Scope": "global" } }, + "SupportedSeries": [ + "precise", + "trusty" + ] "Tags": [ "applications" ] @@ -1353,6 +1360,22 @@ type StatsCount struct { If the refresh boolean parameter is non-zero, the latest stats will be returned without caching. +#### GET *id*/meta/supported-series + +The `supported-series` path returns the OS series that are defined by the entity as +being supported. + +Example: `GET trusty/wordpress-42/meta/supported-series` + +```json +{ + "SupportedSeries": [ + "precise", + "trusty" + ] +} +``` + #### GET *id*/meta/tags The `tags` path returns any tags that are associated with the entity. @@ -1376,6 +1399,10 @@ newer revisions. The fully qualified ids of those charms will be returned in an ordered list from newest to oldest revision. Note that the current revision will be included in the list as it is also an available revision. +If a charm supports multiple series, and the series is not specified in the +request URL, the returned list of ids will be expanded to include separate +entries for each series. Results are ordered by series, most recent first. + ```go type RevisionInfo struct { Revisions []*charm.Reference @@ -1395,12 +1422,31 @@ Example: `GET trusty/wordpress-42/meta/revision-info` } ``` +Example: `GET wordpress/meta/revision-info` + +```json +{ + "Revisions": [ + "cs:trusty/wordpress-43", + "cs:trusty/wordpress-42", + "cs:trusty/wordpress-41", + "cs:trusty/wordpress-39" + "cs:precise/wordpress-41", + "cs:precise/wordpress-39" + ] +} +``` + #### GET *id*/meta/id The `id` path returns information on the charm or bundle id, split apart into its various components, including the id itself. The information is exactly that contained within the entity id. +The request URL may omit series. For charms which support multiple series +in metadata, the Series attribute will be the default series for the charm. +Otherwise the Series will be set to the charm store default. + ```go type Id struct { Id *charm.Reference @@ -1434,6 +1480,17 @@ Example: `GET precise/wordpress/meta/id` } ``` +Example: `GET wordpress/meta/id` + +```json +{ + "Id": "trusty/wordpress-42", + "Series": "trusty", + "Name": "wordpress", + "Revision": 42 +} +``` + Example: `GET bundle/openstack/meta/id` ```json @@ -1516,6 +1573,11 @@ The `id-series` path returns information on the series in the id. This information is exactly that contained within the id. For bundles, this will return "bundle". +The request URL may omit series. For charms which support multiple series +in metadata, the returned series will be the default series for the charm. +Otherwise the series will be set to the charm store default. + + ```go type Series struct { Series string @@ -1530,6 +1592,14 @@ Example: `GET ~bob/trusty/wordpress-42/meta/id-series` } ``` +Example: `GET wordpress-42/meta/id-series` + +```json +{ + "Series": "trusty" +} +``` + ### Resources **Not yet implemented** @@ -1591,7 +1661,7 @@ whose series is 2. Available filters are: * promulgated - the charm has been promulgated. * provides - interfaces provided by the charm. * requires - interfaces required by the charm. -* series - the charm's series. +* series - the set of series associated with the charm. * summary - the charm's summary text. * description - the charm's description text. * type - "charm" or "bundle" to search only one doctype or the other. @@ -1831,7 +1901,7 @@ prior authorization is required. This endpoint returns a macaroon in JSON format that can be passed to third parties to allow them to access the charm store on the user's behalf. A first party "is-entity" caveat may be added to restrict those -parties so that they can only access a given charmstore entity with a +parties so that they can only access a given charm store entity with a specified id. A delegatable macaroon will only be returned to an authorized user (not From cf874651ee6dca6fd6927e55573693e7af36e8ea Mon Sep 17 00:00:00 2001 From: Ian Booth Date: Fri, 18 Sep 2015 11:41:42 +1000 Subject: [PATCH 2/3] Rename endpoint --- docs/API.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/API.md b/docs/API.md index 65cb195db..60b831790 100644 --- a/docs/API.md +++ b/docs/API.md @@ -413,6 +413,7 @@ Example: `GET /meta` "charm-config", "charm-metadata", "charm-related", + "charm-supported-series", "extra-info", "hash", "hash256", @@ -425,7 +426,6 @@ Example: `GET /meta` "promulgated", "revision-info", "stats", - "supported-series", "tags" ] ``` @@ -569,6 +569,7 @@ Example: `GET foo/meta` "charm-config", "charm-metadata", "charm-related", + "charm-supported-series", "extra-info", "id", "id-name", @@ -579,7 +580,6 @@ Example: `GET foo/meta` "promulgated", "revision-info", "stats", - "supported-series", "tags" ] ``` @@ -1360,12 +1360,12 @@ type StatsCount struct { If the refresh boolean parameter is non-zero, the latest stats will be returned without caching. -#### GET *id*/meta/supported-series +#### GET *id*/meta/charm-supported-series -The `supported-series` path returns the OS series that are defined by the entity as -being supported. +The `charm-supported-series` path returns the OS series that are defined by the charm as +being supported. If no series are declared as supported, an empty list is returned. -Example: `GET trusty/wordpress-42/meta/supported-series` +Example: `GET trusty/wordpress-42/meta/charm-supported-series` ```json { @@ -1376,6 +1376,14 @@ Example: `GET trusty/wordpress-42/meta/supported-series` } ``` +Example: `GET trusty/wordpress-41/meta/charm-supported-series` + +```json +{ + "SupportedSeries": [] +} +``` + #### GET *id*/meta/tags The `tags` path returns any tags that are associated with the entity. @@ -1443,9 +1451,9 @@ The `id` path returns information on the charm or bundle id, split apart into its various components, including the id itself. The information is exactly that contained within the entity id. -The request URL may omit series. For charms which support multiple series -in metadata, the Series attribute will be the default series for the charm. -Otherwise the Series will be set to the charm store default. +For charms which support multiple series in metadata, the Series attribute +will be the default series for the charm. Otherwise the Series will be set +to the charm store default. ```go type Id struct { From 137dd538e601f659b840edecd8c899e5533fe686 Mon Sep 17 00:00:00 2001 From: Ian Booth Date: Mon, 28 Sep 2015 13:04:19 +1000 Subject: [PATCH 3/3] Small doc change --- docs/API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/API.md b/docs/API.md index 60b831790..ed73eebe7 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1669,7 +1669,7 @@ whose series is 2. Available filters are: * promulgated - the charm has been promulgated. * provides - interfaces provided by the charm. * requires - interfaces required by the charm. -* series - the set of series associated with the charm. +* series - the set of series supported by the charm. * summary - the charm's summary text. * description - the charm's description text. * type - "charm" or "bundle" to search only one doctype or the other.