Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add API doc for supported series #429

Open
wants to merge 3 commits into
base: v5-unstable
Choose a base branch
from
Open

Add API doc for supported series #429

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0b1f071
Add API doc for supported series
wallyworld Sep 15, 2015
cf87465
Rename endpoint
wallyworld Sep 18, 2015
137dd53
Small doc change
wallyworld Sep 28, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 83 additions & 5 deletions docs/API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -413,6 +413,7 @@ Example: `GET /meta`
"charm-config",
"charm-metadata",
"charm-related",
"charm-supported-series",
"extra-info",
"hash",
"hash256",
Expand Down Expand Up @@ -568,6 +569,7 @@ Example: `GET foo/meta`
"charm-config",
"charm-metadata",
"charm-related",
"charm-supported-series",
"extra-info",
"id",
"id-name",
Expand Down Expand Up @@ -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"`
}

Expand Down Expand Up @@ -746,6 +749,10 @@ Example: `GET wordpress/meta/charm-metadata`
"Scope": "global"
}
},
"SupportedSeries": [
"precise",
"trusty"
]
"Tags": [
"applications"
]
Expand Down Expand Up @@ -1353,6 +1360,30 @@ type StatsCount struct {

If the refresh boolean parameter is non-zero, the latest stats will be returned without caching.

#### GET *id*/meta/charm-supported-series

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/charm-supported-series`

```json
{
"SupportedSeries": [
"precise",
"trusty"
]
}
```

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.
Expand All @@ -1376,6 +1407,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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This would be awkward to implement as the endpoints don't actually know whether the series was specified in the request or not.

I think that if a charm supports multiple series, the resolved URL will omit the series, so the results would be more like:

Example: `GET wordpress/meta/revision-info`

```json
{
    "Revisions": [
        "cs:wordpress-3",
        "cs:wordpress-2",
        "cs:wordpress-1",
    ]
}

It's an open question whether the endpoint should provide earlier revisions of legacy series-specific entities. Perhaps the answer should be yes - it could provide all earlier revisions with series compatible with the resolved URL.

Given that we don't actually use this endpoint, the point is somewhat moot. Perhaps just leave a TODO?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The endpoints use router.ResolvedURL which will contain an empty series if none is specified in the request. So the endpoint code does know doesn't it?

I do think that the example I gave where the series are listed out is valid. I anticipated that core would use it when upgrading to see what maximum revision of a charm could be used which supports are series currently running workloads for that charm. So if the user types "juju upgrade-charm", juju would make a revision-info call with just the charm name to get the info it needs.

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
Expand All @@ -1395,12 +1430,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.

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
Expand Down Expand Up @@ -1434,6 +1488,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
Expand Down Expand Up @@ -1516,6 +1581,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
Expand All @@ -1530,6 +1600,14 @@ Example: `GET ~bob/trusty/wordpress-42/meta/id-series`
}
```

Example: `GET wordpress-42/meta/id-series`

```json
{
"Series": "trusty"
}
```

### Resources

**Not yet implemented**
Expand Down Expand Up @@ -1591,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 charm's series.
* 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.
Expand Down Expand Up @@ -1831,7 +1909,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
Expand Down