Charmworld API 3 Docs

The charmworld API is a restful, versioned API. All functionality for a given API version can be accessed from paths under $site-root/api/$version. For example, if charmworld is deployed at manage.jujucharms.com, the API root for version 1 is at http://manage.jujucharms.com/api/1/. All API endpoints are sub-paths underneath this.

Terminology

“Approved”, “reviewed”, “official” “recommended” and “promulgated” all mean basically the same thing– that the charm has been examined and found worthy. This is controlled on Launchpad by linking the charm branch to the corresponding sourcepackage in the “charms” distribution.

“Community” charms and bundles are those which have not been examined, or have not been found worthy.

charm-id The path portion of a Charm Store URL. For promulgated charms, this is of the form $series/$name(-$revision), and for non-promulgated charms, this is of the form ~$owner/series/$name(-$revision). Revision may be omitted, in which case the head revision will be used.

bundle-id An identifier of a bundle. Three forms are accepted: ~owner/basket/revision/bundle is the canonical, unchanging bundle id, and works for promulgated and unpromulgated bundles. ~owner/basket/bundle refers to the head revision of a bundle. It appears to be intended to support un-promulgated charms, but it currently supports only promulgated charms (bug #1218949). basket/bundle refers to the head revision of a promulgated bundle.

Endpoint output

The responses from API endpoints typically wrap the results with dicts which contain the item itself and a metadata field indicating the doctype, and possibly other data.

{
  "metadata": {
    "doctype": "charm",
  }
  "charm" {
    /* actual charm output (see below)*/
  }
}

Bundle output format

{
    /* The bundle id */
    'id': '~bac/byobu/4/bat',
    /* The sourcepackage name of the basket branch. */
    'basket_name': 'byobu',
    /* The bzr revision of the basket's branch. */
    'basket_revision': 4,
    /* The bundle name */
    'name': 'bat',
    /* The owner of the basket's branch. /*
    'owner': 'bac',
    /* True if the branch has been deleted since it was first registered. */
    'branch_deleted': False,
    /* The actual bundle, in JSON.
    'data': {
        'series': 'precise',
        'services': {},
        'relations': {}
    },
    /* A user-supplied title. */
    'title': '',
    /* A user-supplied description */
    'description': '',
    /* A URL that the user should be able to use to deploy the bundle. */
    'permanent_url': 'bundle:~bac/byobu/4/bat',
    /* See Terminology */
    'promulgated': False,
}

Charm output format

{
  /* The charm-id for this charm. */
  "id": "precise/apache2-10",
  /* The owner of the charm's Launchpad branch.  Unlike maintainer, this is
   * enforced by Launchpad. */
  "owner": "charmers",
  /* The name of the charm */
  "name": "apache2",
  /* The series the charm is associated with, in its distribution */
  "distro_series": "precise",
  /* The maintainer of the charm, according to metadata.yaml. */
  "maintainer": {
    /* The email address of the charm maintainer. */
    "email": "liam.young@canonical.com",
    /* The full name of the charm maintainer */
    "name": "Liam Young"
  },
  /* The date the charm was created (i.e. the date its branch was created on
   * Launchpad), in JS-compatible ISO8601 */
  "date_created": "2013-02-01T21:15:47Z",
  /* The description of the charm from its metadata. */
  "description": "The Apache Software Foundation's goal is to build a
    secure, efficient\nand extensible HTTP server ...",
  /* The charm revision as seen in the revision file. */
  "revision": 5,
  /* The summary from metadata.yaml */
  "summary": "Apache HTTP Server metapackage",
  /* The Juju providers tested with the charm and their Jenkins status.
   * Possible values: 'SUCCESS', 'FAILURE', 'UNSTABLE', 'ABORTED'. */
  "tested_providers": {
    "ec2": "SUCCESS",
    "local": "SUCCESS",
    "openstack": "SUCCESS"
  },
  /* The URL of the charm in the store. */
  "url": "cs:precise/apache2-10",
  /* The number of downloads of this charm */
  "downloads": 51,
  /* The number of downloads of this charm in the past 30 days */
  "downloads_in_past_30_days": 41,
  /* See Terminology */
  "is_approved": true,
  /* If true, the charm is a subordinate charm. */
  "is_subordinate": false,
  /* Always 0 */
  "rating_denominator": 0,
  /* Always 0 */
  "rating_numerator": 0,
  /* The options of this charm, as seen in config.yaml (but represented as
   * JSON). */
  /* Information related to the charm source files */
  "code_source": {
    /* A link to where bugs on the charm can be reported. */
    "bugs_link": "https://bugs.launchpad.net/charms/+source/apache2",
    /* The last commit message for the charm. */
    "last_log": "[hloeung,r=mthaddon] Fix error below when SSL chain
        certificate file is missing, and create cert from template for
        self-signed cert",
    /* The location where the charm can be found. */
    "location": "lp:~charmers/charms/precise/apache2/trunk",
    /* The vcs revision, as stored in the charm store. */
    "revision": "44",
    /* A list of vcs revisions, from newest to oldest.  At least 10 revisions
       are included, and at least the past 30 days are covered, so this list
       can be used to display the last 10 revisions or count the number of
       commits in the past 30 days. */
    /* The source type, typically "bzr" */
    "type": "bzr",
    /* A list of revisions, applicable when the "type" is "bzr". */
    "revisions": [
      {
        /* A list of the authors of this revision.  With Bazaar, there is
         * typically one author, and this is typically the committer, but
         * this can be overridden in bzr with the --author parameter. */
        "authors": [
          {
            /* The email address of the author.  It is impolite to display
             * this.  Its main function is to uniquely identify the author.
             */
            "email": "tom.haddon@canonical.com",
            /* The full name of the author. */
            "name": "Tom Haddon"
          }
        ],
        /* The date and time the commit was made, in the
         * JavaScript-compatible subset of ISO8601 in UTC. */
        "date": "2013-05-02T10:05:32Z",
        /* The commit message */
        "message": "[hloeung,r=mthaddon] Fix error below when SSL chain
          certificate file is missing, and create cert from template for
          self-signed cert",
        /* The vcs revision number of the revision */
        "revno": 44
      }
    ],
  },
  /* A list of the files in this charm that are accessible, as paths from
   * the charm root. */
  "files": [
    "hooks/website-relation-joined",
    "hooks/balancer-relation-broken",
  ],
  "options": {
    "config_change_command": {
      "default": "reload",
      "description": "The command to run whenever config has changed.",
      "type": "string"
    }
  },
  /* A mapping of the charm's relations, as seen in metadata.yaml */
  "relations": {
    "provides": {
      "nrpe-external-master": {
        "interface": "nrpe-external-master",
        "scope": "container"
      }
    },
    "requires": {
      "balancer": {
        "interface": "http"
      }
    }
  }
}

Listing charms and bundles

Charm and bundle listings are provided by the search endpoint using the GET method. This lists all well-formed charms and bundles that match query parameters.

Query parameter	Description
text	Text that the item must match. See below for more details.
autocomplete	Search for autocompletions. This will match only on the name field, and will match on prefixes of the name.
categories, name, owner, provides, provider, requires, series, summary	Used as a filter. Each filter parameter may be repeated. Items matching any of the selected values for a filter are selected, so name=1&name=2 would match items whose name was either 1 or 2. However, if multiple filters are specified, the charm must match all of them, so name=1&series=2 will only match charms whose name is 1 and whose series is 2. Filters on lists of values (categories, requires, provides) match on a single element of the list. So if a charm requires both http and ftp, requires=http will match it.
type	If specified, must be appproved or community. (See Terminology)
limit	The maximum number of items to return. By default, all matching items are returned.

Text matching

For charms, the following fields are considered for partial matches: summary, description, config option description, relations, store_url, and interface names. Additionally, the following fields will match if the text exactly matches the contents of that field: name, owner, series.

For bundles, the following fields are considered for partial matches: basket, description, title, charm names. Additionally, the following fields will match if the text exactly matches the contents of that field: name, owner, series.

Listing front-page charms and bundles

The front-page items are retrieved by performing a GET to search/interesting.

The result is a mapping of new, featured and popular charms and bundles. new is a list of the 10 most recently-created items (according to their Launchpad branches), from most to least-recently created. popular is a list of the 10 most-downloaded items, from most to least-downloaded. featured is a list of all items that have been manually selected as featured, in unspecified order.

Retrieving an individual charm

An individual charm can be retrieved by invoking GET on charm/$charm-id, where the charm-id is appended to the path without escaping. So if the charm-id is precise/foobar, the path is charm/precise/foobar, not charm/precise%2ffoobar.

Retrieving related charms

Information about which charms are related to a charm can be retrieved by invoking GET on charm/$charm-id/related. For example, if the charm-id is precise/foobar, the path to the endpoint is charm/precise/foobar/related.

Charms are considered “related” to a given charm if

1. They provide an interface that the charm requires, or
2. They require an interface that the charm provides, and
3. Their series is the same as the charm’s [1] and
4. Their name is different from the charm’s.

The API call returns a mapping in which result.provides includes all charms that provide interfaces used by the charm, organized by interface, and result.requires includes all charms that require interfaces provided by the charm.

As an example:

{
  result: {
    requires: {
      http: [/* list of charms that require http*/],
      sftp: [/* list of charms that require sftp*/]
    }
    provides: {
      bluetooth: [/* list of charms that provide bluetooth */]
    }
  }
}

An abbreviated form is used for related charms:

{
  /* The charm-id of this charm */
  "id": "precise/limesurvey-4",
  /* The name of this charm */
  "name": "limesurvey",
  /* True if the charm has an icon.svg file. */
  "has_icon": true,
  /* The categories associated with the charm. */
  "categories": [],
  /* The number of downloads of this charm */
  "downloads": 51,
  /* The number of downloads of this charm in the past 30 days */
  "downloads_in_past_30_days": 41,
  /* The number of commits to this charm in the past 30 days */
  "commits_in_past_30_days": 5,
  /* See Terminology_ */
  "is_approved": true,
  /* The weight of this charm, for sorting purposes.
   * Weights are relative to other weights-- their
   * absolute value has no meaning. */
  "weight": 10.0
},

[1]	While it is technically possible for charms in different series to be deployed in the same environment, we believe this is an unusual thing to do, and an unhelpful thing to suggest.

Retrieving the files that make up a charm

The contents of a file in a charm can be retrieved by invoking GET on charm/$charm-id/file/$path. For example, if the file is hooks/install and the charm-id is precise/foobar, the path is charm/precise/foobar/file/hooks/install.

Not all charm files are available. The available files are listed in the files member of the charm, and include icon.svg, readme.*, config.yaml, metadata.yaml, revision, hooks/*.

Retrieving the icon for a charm

The icon for a charm can be one of several.

• If the charm provided an icon and it is a reviewed charm we return the actual svg provided.
• If the charm is not reviewed, but has a category then we create a redirect to a fallback icon.
• Else we redirect to a generic icon.

Retrieving the icon for a charm given a charm id

charm/$charmid/file/icon.svg will respond with either an icon or a 302 redirect to an icon that can be used for the charm.

Resolving an icon without a charm id

You can still get an icon for a charm without a charm id. Bundles may specify the charm in them in many formats. The API supports getting directed to the correct charm icon in any of the following ways:

• store_url: charm/resolve-icon/cs:series/charm-revision
• launchpad branch: charm/resolve-icon/lp:xxxxxxxx
• launchpad branch with revision: charm/resolve-icon/lp:xxxxxxxx@revison
• latest revision of a promulgated charm: charm/resolve-icon/series/name

Retrieving QA data

The results of QA review of a charm can be retrieved by invoking GET on charm/$charm-id/qa. The return value is formed like this:

{
  "result": {
    /* A list of the current questions */
    "questions": [
      /* A question heading */
      {
        /* The display name of the heading */
        "description": "Data Handling",
        /* The unique name of the heading */
        "name": "data_handling",
        /* A list of the questions for this heading */
        "questions": [
          {
            /* A description of the question */
            "description": "Integrate data storage best practices",
            /* More questions */
            "extended_description": "Backups based on service usage",
            /* The question id */
            "id": "data_handling_0",
            /* The point score for this question */
            "points": 1
          },
        ]
      },
    ],
    "scores": {
      /* Scores for a heading */
      "data_handling": {
        /* Answer to a question, one of "0" (no), "1" (yes) or "" (unknown).
         */
        "data_handling_0": "1"
      }
    }
  }

Retrieving a bundle

A bundle can be retrieved by invoking GET on bundle/$bundle-id, where the bundle-id is appended to the path without escaping. So if the bundle-id is apache2/with-squid, the path is bundle/apache2/with-squid.

The results are in bundle output format, without the typical endpoint output wrapper.

Retrieving the icon for a bundle

The icon for a bundle can currently only be the default. You may request it based on the bundle’s id.

bundle/$bundleid/file/icon.svg will respond with a 302 redirect to an icon that can be used for the bundle.