===================== 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. .. _bug #1218949: https://bugs.launchpad.net/charmworld/+bug/1218949 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``, | Used as a filter. Each filter parameter may be | | ``name``, | repeated. Items matching any of the selected values | | ``owner``, | for a filter are selected, so ``name=1&name=2`` would | | ``provides``, | match items whose name was either ``1`` or ``2``. | | ``provider``, | However, if multiple filters are specified, the charm | | ``requires``, | must match all of them, so ``name=1&series=2`` will only | | ``series``, | match charms whose name is ``1`` *and* whose series is | | ``summary`` | ``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.