~jcsackett/charmworld/bac-tag-constraints

=====================
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.

The results provide many fields of metadata about the bundle including:

:charm_metadata: The details for each charm found within the bundle. This
                 includes the same data that finding the charm directly would
                 include.

:files: The list of files that make up the original submitted bundle including
        the README.md

:changes: The recent list of changes made to the ingested bundle repository.


Retrieving files from a bundle
==============================
The contents of a file in a bundle can be retrieved by invoking GET on
``bundle/$charm-id/file/$path``.  For example, if the file is ``README``
and the bundle-id is ``~user/wiki/TestBundle```, the path is
``bundle/~user/wiki/TestBundle/file/README``.


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.

Proofing a bundle
=================
A deployer file containing bundles can be checked to verify that the charms
specified in the bundles are in fact valid and found in the store. It will
also check that the configuration options specified match those from the
charms found. Finally, it will also verify that any relations constructed are
also valid for the charms found.

You can fetch this information by submitting a ``POST`` request with the data
``deployer_file`` to ``bundle/proof``. This will then be processed and checked
for errors. A sample request with response is listed below.

::


    http --form POST https://manage.jujucharms.com/api/3/bundle/proof
      deployer_file='{ "wiki": { "services": { "wiki": { "charm": "mediawiki",
        "num_units": 2, "branch": "lp:charms/precise/mediawiki", "constraints":
        "mem=2" }, "haproxy": { "options": { "request-limit": 32 }, "branch":
        "lp:charms/precise/haproxy" }, "db": { "charm": "mysql", "options": {
        "tuning-level": "fast" }, "branch": "lp:charms/precise/mysql" },
        "memcached": { "options": { "request-limit": 32 }, "branch":
        "lp:charms/precise/memcached" } }, "series": "precise", "promulgated":
        true, "relations": [ [ "wiki:db", "memcached" ], [ "db", [ "haproxy", "db"
        ] ] ] } }'

    HTTP/1.0 200 OK
    Access-Control-Allow-Headers: X-Requested-With
    Access-Control-Allow-Origin: *
    Content-Length: 1360
    Content-Type: application/json
    Date: Mon, 04 Nov 2013 13:48:53 GMT
    Server: PasteWSGIServer/0.5 Python/2.7.4

    {
        "debug_info": [],
        "error_messages": [
            "wiki: The charm has no option for: request-limit",
            "wiki: Invalid relation on interface: db",
            "wiki: The two services db:haproxy share no common interfaces."
        ],
        "errors": [
            {
                "name": "wiki",
                "relations": [
                    {
                        "debug_info": [
                            "wiki:db <-> memcached"
                        ],
                        "message": "Invalid relation on interface: db"
                    },
                    {
                        "debug_info": [
                            "db <-> haproxy"
                        ],
                        "message": "The two services db:haproxy share no common interfaces."
                    }
                ],
                "services": {
                    "haproxy": [
                        {
                            "debug_info": [
                                "Looking at charm id: ~charmers/precise/haproxy/19",
                                "Found config keys: [u'sysctl', u'default_retries', u'global_group', u'monitoring_stats_refresh', u'default_options', u'global_user', u'monitoring_password', u'default_mode', u'default_timeouts', u'global_log', u'global_spread_checks', u'monitoring_allowed_cidr', u'monitoring_username', u'default_log', u'package_status', u'services', u'global_maxconn', u'monitoring_port', u'global_debug', u'nagios_context', u'global_quiet', u'enable_monitoring']"
                            ],
                            "message": "The charm has no option for: request-limit"
                        }
                    ]
                }
            }
        ]
    }