← Back to branch summary

~juju-qa/ubuntu/xenial/juju/xenial-2.0-beta3

« back to all changes in this revision

Viewing changes to src/gopkg.in/juju/charmstore.v5-unstable/docs/API.md

  • Committer: Martin Packman
  • Date: 2016-03-30 19:31:08 UTC
  • mfrom: (1.1.41)
  • Revision ID: martin.packman@canonical.com-20160330193108-h9iz3ak334uk0z5r
Merge new upstream source 2.0~beta3

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/gopkg.in/juju/charmstore.v5-unstable/docs/API.md
32
32
consume the format, along with an example. A charm id is represented as a
33
33
`charm.URL type`.
34
34
 
35
 
 
36
35
### Errors
37
36
 
38
37
If any request returns an error, it will produce it in the following form:
94
93
public information is returned. In this case, results requiring authorization
95
94
(if any) will be omitted.
96
95
 
 
96
### Channels
 
97
 
 
98
Any entity in the charm store is considered to be part of one or more "channels"
 
99
(think "distribution channels"). Currently supported channels are "unpublished",
 
100
"development" and "stable". All entities are initially (and always) part
 
101
of the "unpublished" channel; subsequent operations on the publish
 
102
endpoint can make entities available in other channels.
 
103
 
 
104
All requests that take one or more entity ids as parameters
 
105
accept a "channel" query parameter that influences what channel
 
106
is chosen to resolve the ids. The default channel is "stable".
 
107
 
 
108
For example, if wordpress-3 has just been published to the stable
 
109
channel, and wordpress-4 has been published to the development
 
110
 then a GET of wordpress/meta/id-revision?channel=development
 
111
will return {"Revision": 4} and a GET of wordpress/wordpress/meta/id-revision
 
112
will return {"Revision": 3} because the default channel is "stable".
 
113
 
97
114
### Versioning
98
115
 
99
116
The version of the API is indicated by an initial "vN" prefix to the path.
103
120
`wordpress/meta/charm-metadata` path is actually at
104
121
`v4/wordpress/meta/charm-metadata`.
105
122
 
106
 
 
107
123
### Boolean values
108
124
 
109
125
Where a flag specifies a boolean property, the value must be either "1",
282
298
 
283
299
#### PUT *id*/publish
284
300
 
285
 
A PUT to ~*user*/*anyseries*/*name*-*anyrevision* sets whether the
286
 
corresponding charm or bundle is published and can be accessed through a URL
287
 
with no channel. If the revision number is not specified, the id is resolved to
288
 
the charm or bundle with the latest development revision number when
289
 
publishing, and to the charm or bundle with the latest non-development revision
290
 
number when unpublishing. The id must not include the development channel.
 
301
A PUT to the publish endpoint publishes the entity with the given id
 
302
on the channels provided in the request body. It reports an error if
 
303
there are no channels specified or if one of the channels is invalid
 
304
(the "unpublished" channel is special and is also considered invalid in
 
305
a publish request).
 
306
 
 
307
See the section on Channels in the introduction for how the published
 
308
channels affects id resolving.
291
309
 
292
310
```go
293
311
type PublishRequest struct {
294
 
    Published bool
295
 
}
296
 
```
297
 
 
298
 
If Published is true, the charm or bundle is made available at the
299
 
non-development URL with the same revision number. If Published is false, the
300
 
id is unpublished.
301
 
 
302
 
The response includes the id and promulgated id of the entity after the action
303
 
is performed:
304
 
 
305
 
```go
306
 
type PublishResponse struct {
307
 
    Id            *charm.URL
308
 
    PromulgatedId *charm.URL `json:",omitempty"`
309
 
}
310
 
```
311
 
 
312
 
If the charm or bundle have been unpublished, the identifiers in the response
313
 
will represent the corresponding development charm or bundle.
 
312
    Channels []string
 
313
}
 
314
```
 
315
 
 
316
On success, the response body will be empty.
314
317
 
315
318
Example: `PUT ~charmers/trusty/django-42/publish`
316
319
 
317
320
Request body:
318
321
```json
319
322
{
320
 
    "Published" : true,
 
323
    "Channels" : ["stable"],
321
324
}
322
325
```
323
326
 
324
 
Response body:
325
 
```json
326
 
{
327
 
    "Id" : "cs:~charmers/trusty/django-42",
328
 
    "PromulgatedId": "cs:trusty/django-10",
329
 
}
330
 
```
 
327
After the above request, ~charmers/trusty/django will
 
328
resolve to ~charmers/trusty/django-42 unless a different
 
329
channel is specified in the request.
331
330
 
332
331
### Stats
333
332
 
489
488
    "id-user",
490
489
    "manifest",
491
490
    "promulgated",
 
491
    "published",
492
492
    "revision-info",
493
493
    "stats",
494
494
    "supported-series",
1073
1073
}
1074
1074
```
1075
1075
 
 
1076
#### GET *id*/meta/published
 
1077
 
 
1078
The `meta/published` path returns a list of the channels that
 
1079
the entity has been published to.
 
1080
 
 
1081
```go
 
1082
type PublishedResponse struct {
 
1083
        // Info holds an entry for each channel that the
 
1084
        // entity has been published to.
 
1085
        Info []PublishedInfo
 
1086
}
 
1087
 
 
1088
// PublishedInfo holds information on a channel that an entity
 
1089
// has been published to.
 
1090
type PublishedInfo struct {
 
1091
        // Channel holds the value of the channel that
 
1092
        // the entity has been published to.
 
1093
        // This will never be "unpublished" as entities
 
1094
        // cannot be published to that channel.
 
1095
        Channel Channel
 
1096
 
 
1097
        // Current holds whether the entity is the most
 
1098
        // recently published member of the channel.
 
1099
        Current bool
 
1100
}
 
1101
```
 
1102
 
 
1103
#### GET *id*/meta/terms
 
1104
 
 
1105
The `meta/terms` path returns a list of terms and conditions (as recorded in
 
1106
the terms field of the charm metadata) the user must agree to in order to 
 
1107
obtain the archive of the given charm id.
 
1108
 
 
1109
Example: `GET some-charm/meta/terms`
 
1110
 
 
1111
```json
 
1112
[
 
1113
    "enterprise-terms/1",
 
1114
    "special-terms/17"
 
1115
]
 
1116
```
 
1117
 
1076
1118
#### GET *id*/meta/archive-size
1077
1119
 
1078
1120
The `meta/archive-size` path returns the archive size, in bytes, of the archive