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 1 commit
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
80 changes: 75 additions & 5 deletions docs/API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -425,6 +425,7 @@ Example: `GET /meta`
"promulgated",
"revision-info",
"stats",
"supported-series",
"tags"
]
```
Expand Down Expand Up @@ -578,6 +579,7 @@ Example: `GET foo/meta`
"promulgated",
"revision-info",
"stats",
"supported-series",
"tags"
]
```
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,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
Copy link
Contributor

Choose a reason for hiding this comment

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

s/entity/charm/ ?

I think I'd call this endpoint charm-supported-series, as it's charm-specific,
and like other charm-specific endpoints, it'll return a metadata-not-found error when invoked on bundles.

Also, we should be clear about the behaviour when the charm metadata does not support multiple series.

Copy link
Member Author

Choose a reason for hiding this comment

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

I've renamed to charm-supported-series and added an extra example to show how an empty list is returned if no supported series are declared in the metadata.

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

Choose a reason for hiding this comment

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

The first sentence is redundant - the series may always be omitted from an id.

Returning the preferred series when there are multiple supported series may be problematic. Currently it is an invariant that a resolved URL (which is exactly what meta/id is returning) refers directly to entity entry in the charm store. Changing this may break quite a bit of code.

Ideally I'd like the API to change so that a resolved id for a multi-series charm does not contain the series, but this could be considered a backwardly incompatible change, and old clients will then refuse to deploy multi-series charms.

One possibility is to create a new version of the API (ideally by copying the entire API implementation into v5 and creating v4 layering on top of v5), but this would require some thought.

Copy link
Member Author

Choose a reason for hiding this comment

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

Quick response to this one point - old clients do need to be able to deploy multi series charms. There was discussion that when a multi-series charm is published, separate entity entries would be created for each supported series. When you say code will break, do you mean charmstore code? Could it not be changed to be able to look for an entity with series in the id and revert to an id without series if not found?

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 +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
Expand Down Expand Up @@ -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
Expand All @@ -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**
Expand Down Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

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

a series supported by the charm

?

(this endpoint is used, and I don't think its semantics need to change)

Copy link
Member Author

Choose a reason for hiding this comment

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

I don't follow. The endpoint currently accepts 0 or 1 series as parameter values. We now just allow it to accept > 1.
name=foo&series=precise&series=trusty

Existing use cases will work just fine, as will new callers be able to specify additonal series to filter on. This will be something I anticipate juju may use.

Copy link
Contributor

Choose a reason for hiding this comment

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

It seems that this is something that should be added when it's needed though. It's not been needed to date, and it seems that to find a series supported for a charm there'd be better methods vs a elasticsearch search. I'm with @rogpeppe that until something comes up that requires it directly that we don't go changing things on the chance they might be needed.

* 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 +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
Expand Down