<commit_before>.. _submission:

======================
Submission API
======================

Adding an app follows a few steps, roughly analgous to the flow in a browser.
Validate your app, add it in, update it with the various data and
then request review.

Validate
========

.. note:: The validation does not require you to be authenticated, however you
    cannot create apps from those validations. To validate and submit an app
    you must be authenticated for both steps.

To validate a hosted app::

        POST /api/apps/validation/
        {"manifest": "http://test.app.com/manifest"}

To validate a packaged app, send the appropriate file data in the upload field.
File data is a dictionary of name, type (content type) and the base 64 encoded
data. For example::

        POST /api/apps/validation/
        {"upload": {"type": "application/foo",
                    "data": "UEsDBAo...gAAAAA=",
                    "name": "mozball.zip"}}

This will return the result of the validation as below. Hosted apps are done
immediately but packaged apps are queued. Clients will have to poll the results
URL until the validation has been processed.

To query the result::

        GET /api/apps/validation/123/

This will return the status of the validation. An example of a validation not processed yet::

        {"id": "123",
         "processed": false,
         "resource_uri": "/api/apps/validation/123/",
         "valid": false,
         "validation": ""}

Example of a validation processed and good::

        {"id": "123",
         "processed": true,
         "resource_uri": "/api/apps/validation/123/",
         "valid": true,
         "validation": ""}

Example of a validation processed but with an error::

        {"id": "123",
         "processed": true,
         "resource_uri": "/api/apps/validation/123/",
         "valid": false,
         "validation": {
           "errors": 1, "messages": [{
             "tier": 1,
             "message": "Your manifest must be served with the HTTP header \"Content-Type: application/x-web-app-manifest+json\". We saw \"text/html; charset=utf-8\".",
             "type": "error"
           }],
        }}

Create
======

.. note:: Requires authentication and a successfully validated manifest.

To create an app with your validated manifest the body data should contain the
manifest id from the validate call and other data in JSON::


        POST /api/apps/app/
        {"manifest": "123"}

If you'd like to create a successfully validation packaged app, use upload
instead of manifest::

        POST /api/apps/app/
        {"upload": "123"}

If the creation succeeded you'll get a 201 status back. This will return the id
of the app on the marketplace as a slug. The marketplace will complete some of
the data using the manifest and return values so far::

        {"categories": [],
         "description": null,
         "device_types": [],
         "homepage": null,
         "id": 1,
         "manifest": "0a650e5e4c434b5cb60c5495c0d88a89",
         "name": "MozillaBall",
         "premium_type": "free",
         "privacy_policy": null,
         "resource_uri": "/api/apps/app/1/",
         "slug": "mozillaball",
         "status": 0,
         "summary": "Exciting Open Web development action!",
         "support_email": null,
         "support_url": null
        }

Fields:

* `manifest` (required): the id of the manifest returned from verfication.

Update
======

.. note:: Requires authentication and a successfully created app.

Put your app to update it. The body contains JSON for the data to be posted::

        PUT /api/apps/app/<app id>/

These are the fields for the creation and update of an app. These will be
populated from the manifest if specified in the manifest. Will return a 202
status if the app was successfully updated.

Fields:

* `name` (required): the title of the app. Maximum length 127 characters.
* `summary` (required): the summary of the app. Maximum length 255 characters.
* `categories` (required): a list of the categories, at least two of the
  category ids provided from the category api (see below).
* `description` (optional): long description. Some HTML supported.
* `privacy_policy` (required): your privacy policy. Some HTML supported.
* `homepage` (optional): a URL to your apps homepage.
* `support_url` (optional): a URL to your support homepage.
* `support_email` (required): the email address for support.
* `device_types` (required): a list of the device types at least one of:
  'desktop', 'mobile', 'tablet', 'firefoxos'. 'mobile' and 'tablet' both refer
  to Android mobile and tablet. As opposed to Firefox OS.
* `payment_type` (required): only choice at this time is 'free'.

Example body data::

        {"privacy_policy": "wat",
         "name": "mozball",
         "device_types": ["desktop-1"],
         "summary": "wat...",
         "support_email": "<EMAIL>",
         "categories": [1L, 2L],
         "previews": []
         }

Previews will be list of URLs pointing to the screenshot API.

List
====

.. note:: Requires authentication.

To get a list of the apps you have available::

        GET /api/apps/app/

This will return a list of all the apps the user is allowed to access::

        {"meta": {"limit": 20,
                  "next": null,
                  "offset": 0,
                  "previous": null,
                  "total_count": 2},
         "objects": [
                {"categories": [1L],
                 "resource_uri": "/api/apps/app/4/"
                 ...]}
        }

Get
===

.. note:: Requires authentication.

To get an individual app, use the `resource_uri` from the list::

        GET /api/apps/app/4/

This will return::

        {"resource_uri": "/api/apps/app/4/",
         "slug": "mozillaball",
         "summary": "Exciting Open Web development action!",
         ...}<commit_msg>add in docs (bug 833591)<commit_after>.. _submission:

======================
Submission API
======================

Adding an app follows a few steps, roughly analgous to the flow in a browser.
Validate your app, add it in, update it with the various data and
then request review.

Validate
========

.. note:: The validation does not require you to be authenticated, however you
    cannot create apps from those validations. To validate and submit an app
    you must be authenticated for both steps.

To validate a hosted app::

        POST /api/apps/validation/
        {"manifest": "http://test.app.com/manifest"}

To validate a packaged app, send the appropriate file data in the upload field.
File data is a dictionary of name, type (content type) and the base 64 encoded
data. For example::

        POST /api/apps/validation/
        {"upload": {"type": "application/foo",
                    "data": "UEsDBAo...gAAAAA=",
                    "name": "mozball.zip"}}

This will return the result of the validation as below. Hosted apps are done
immediately but packaged apps are queued. Clients will have to poll the results
URL until the validation has been processed.

To query the result::

        GET /api/apps/validation/123/

This will return the status of the validation. An example of a validation not processed yet::

        {"id": "123",
         "processed": false,
         "resource_uri": "/api/apps/validation/123/",
         "valid": false,
         "validation": ""}

Example of a validation processed and good::

        {"id": "123",
         "processed": true,
         "resource_uri": "/api/apps/validation/123/",
         "valid": true,
         "validation": ""}

Example of a validation processed but with an error::

        {"id": "123",
         "processed": true,
         "resource_uri": "/api/apps/validation/123/",
         "valid": false,
         "validation": {
           "errors": 1, "messages": [{
             "tier": 1,
             "message": "Your manifest must be served with the HTTP header \"Content-Type: application/x-web-app-manifest+json\". We saw \"text/html; charset=utf-8\".",
             "type": "error"
           }],
        }}

Create
======

.. note:: Requires authentication and a successfully validated manifest.

To create an app with your validated manifest the body data should contain the
manifest id from the validate call and other data in JSON::


        POST /api/apps/app/
        {"manifest": "123"}

If you'd like to create a successfully validation packaged app, use upload
instead of manifest::

        POST /api/apps/app/
        {"upload": "123"}

If the creation succeeded you'll get a 201 status back. This will return the id
of the app on the marketplace as a slug. The marketplace will complete some of
the data using the manifest and return values so far::

        {"categories": [],
         "description": null,
         "device_types": [],
         "homepage": null,
         "id": 1,
         "manifest": "0a650e5e4c434b5cb60c5495c0d88a89",
         "name": "MozillaBall",
         "premium_type": "free",
         "privacy_policy": null,
         "resource_uri": "/api/apps/app/1/",
         "slug": "mozillaball",
         "status": 0,
         "summary": "Exciting Open Web development action!",
         "support_email": null,
         "support_url": null
        }

Fields:

* `manifest` (required): the id of the manifest returned from verfication.

Update
======

.. note:: Requires authentication and a successfully created app.

Put your app to update it. The body contains JSON for the data to be posted::

        PUT /api/apps/app/<app id>/

These are the fields for the creation and update of an app. These will be
populated from the manifest if specified in the manifest. Will return a 202
status if the app was successfully updated.

Fields:

* `name` (required): the title of the app. Maximum length 127 characters.
* `summary` (required): the summary of the app. Maximum length 255 characters.
* `categories` (required): a list of the categories, at least two of the
  category ids provided from the category api (see below).
* `description` (optional): long description. Some HTML supported.
* `privacy_policy` (required): your privacy policy. Some HTML supported.
* `homepage` (optional): a URL to your apps homepage.
* `support_url` (optional): a URL to your support homepage.
* `support_email` (required): the email address for support.
* `device_types` (required): a list of the device types at least one of:
  'desktop', 'mobile', 'tablet', 'firefoxos'. 'mobile' and 'tablet' both refer
  to Android mobile and tablet. As opposed to Firefox OS.
* `payment_type` (required): only choice at this time is 'free'.

Example body data::

        {"privacy_policy": "wat",
         "name": "mozball",
         "device_types": ["desktop-1"],
         "summary": "wat...",
         "support_email": "<EMAIL>",
         "categories": [1L, 2L],
         "previews": []
         }

Previews will be list of URLs pointing to the screenshot API.

List
====

.. note:: Requires authentication.

To get a list of the apps you have available::

        GET /api/apps/app/

This will return a list of all the apps the user is allowed to access::

        {"meta": {"limit": 20,
                  "next": null,
                  "offset": 0,
                  "previous": null,
                  "total_count": 2},
         "objects": [
                {"categories": [1L],
                 "resource_uri": "/api/apps/app/4/"
                 ...]}
        }

Get
===

.. note:: Requires authentication if the app is not public.

To get an individual app, use the `resource_uri` from the list::

        GET /api/apps/app/4/

This will return::

        {"resource_uri": "/api/apps/app/4/",
         "slug": "mozillaball",
         "summary": "Exciting Open Web development action!",
         ...}
{'fraction_non_alphanumeric': 0.12312925170068027, 'fraction_numerical': 0.013945578231292517, 'mean_word_length': 2.5520990637269705, 'pattern_counts': {'":': 122, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1053247', 'n_tokens_mistral': 3412, 'n_tokens_neox': 3160, 'n_words': 1350}