This document is a draft / work in progress as this API is still in development. Please contact us, if you would like to begin using this API.

About Apps API

Mozello Apps API allows to place your app in the Mozello Apps catalog (formerly known as Extras). This API should be used in conjunction with other Mozello APIs, especially Store API.

For example, if you have an accounting app that integrates with Mozello using Store API, you can now prominently show your app in the Mozello Apps catalog and provide an easy one-click install.

API calls

Basics

The base URL for all API calls is https://api.mozello.com/v1/

For Apps, authCode query parameter must be added.
https://api.mozello.com/v1/?authCode=xxxxx
You will obtain authCode during installation process.

API calls are made to the corresponding API URL which, in turn responds with a JSON object. Optional properties might be omitted or returned as null. The returned HTTP status will be 200 for successful or partially successful API calls, and 4XX or 5XX for unsuccessful API calls.

GET, POST, PUT and DELETE HTTP methods are used for standard API methods that perform Get, Create, Update and Delete actions with a resource. POST HTTP method is used for non-standard methods.

Payloads are in JSON format.

For authentication API key must be sent in an HTTP header of each request:

Authorization: ApiKey MZL-d4fcd4c02c88eafaeaef7f87f6796f12

Example

Request (raw HTTP)

GET /v1/apps/languages/?authCode=xxxxx HTTP/1.1
Host: api.mozello.com

Success response

{
    "error": false,
    "languages": ["en", "de", "fr"]
}

Error response

{
    "error": true,
    "error_code": 401,
    "error_message": "Unauthorized"
}

Mark as installed

POST /apps/installed/ - mark app as installed.

Marks installed app instance as finished installing. This method must be called to finish the app installation process.

Parameters

none

Uninstall

POST /apps/delete/ - uninstall app.

Uninstalls app from the website. Uninstalling app will clear all app snippets and data.

Parameters

none

Set code snippet

POST /apps/set_snippet/ - set HTML code snippet.

Sets code snippet to be included in HTML body of every page or only pages in specified language, if language parameter used.

Parameters

  • snippet - string.
  • language - string, optional - language code.

Example

Set code snippet:

{
    "snippet": "<script src='//example.org/examplescript.js' type='text/javascript'></script>"
}

Get code snippet

GET /apps/get_snippet/ - get HTML code snippet.

Gets current code snippet set by set_snippet API call.

Example return data:

{
    "snippet": "<script src='//example.org/examplescript.js' type='text/javascript'></script>"
}

Get code snippet for language

GET /apps/get_snippet/<language>/ - get HTML code snippet for language.

Gets current code snippet set by set_snippet API call for specified language.

Example return data:

{
    "snippet": "<script src='//example.org/examplescript.js' type='text/javascript'></script>"
}

Set data

POST /apps/set_data/ - set configuration data.

Sets data for the installed app instance. Any user configuration for the app can be stored here.

Parameters

  • data - string/object.

Example

Set data:

{
    "data": {
        "example_property_1": "Example",
        "example_property_2": "Example"
    }
}

Get data

GET /apps/get_data/ - get configuration data.

Gets data set by set_data API call.

Example return data:

{
    "data": {
        "example_property_1": "Example",
        "example_property_2": "Example"
    }
}

Get user info

GET /apps/user/ - get user info.

Gets basic user info.

Example return data:

{
    "user": {
        "email": "example@example.org",
        "email_confirmed": false
    }
}

Get website info

GET /apps/website/ - get website info.

Gets basic website info.

Example return data:

{
    "website": {
        "url": "https://www.example.org/",
        "brandname": "example"
    }
}

Get website languages

GET /apps/languages/ - get website languages.

Gets list of languages used in the website.

Example return data:

{
    "languages": ["en", "de", "fr"]
}

Creating App

Basics

To create Mozello App, the following steps need to be taken:

  • App must be hosted on your web server. HTTPS (SSL) connecton is mandatory. App must interact with Mozello websites via API (Apps API, Store API).
  • App manifest must be created and submitted to App integration setup portal, to be added to Mozello Apps catalog.
  • App must support Mozello App installation process, to allow Mozello users to install the App to their website.

The integration process

This process will add your App to Mozello Apps catalog and assign API key for your App.

The process:

  1. Create a Mozello account for testing
  2. Submit your integration manifest via App integration setup portal and receive your API key
  3. Implement Mozello App installation process for your App
  4. Submit your integration for approval via App integration setup portal
  5. Upon successful approval, your integration will go live
  6. Update your integration details via App integration setup portal any time
  7. Re-submit modified integration details for approval via App integration setup portal

Please keep your API key secret and prevent any possible public access to your API key.

App manifest

Submit a structured data manifest (in JSON format) containing information about your App.

Upon signing up and submitting the manifest, you will receive a secret key that App must use for API authentication.

Manifest example

{
    "app_type": "APP",
    "app_title": "Hello World",
    "app_icon": "https://www.example.org/icons/app.png",
    "app_version": "1.0.0",
    "app_description_short": {
        "en": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    },
    "app_description_full": {
        "en": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque pretium nulla a tincidunt hendrerit. Nullam lacinia, leo quis vestibulum pretium, mauris metus laoreet sem, vitae bibendum justo eros porta neque. Praesent semper sit amet magna bibendum convallis. Proin non lorem id enim imperdiet maximus sed ut turpis."
    },
    "app_screenshots": {
        "en": "https://www.example.org/icons/screenshot.png"
    },
    "app_vendor": {
        "company_name": "Company",
        "support_email": "support@example.org",
        "support_phone": "+1 555 0101 1234",
        "developer_email": "developer@example.org",
        "company_url": "https://www.example.org",
        "support_url": "https://www.example.org/support/",
        "privacy_url": "https://www.example.org/privacy/",
        "tos_url": "https://www.example.org/tos/"
    },
    "app_permissions": ["FULL"],
    "app_tab_mode": "blank",
    "app_install_url": "https://www.example.org/helloworld/install.php",
    "app_settings_url": "https://www.example.org/helloworld/settings.php",
    "app_secret": "RYdabN4UPtjG2YJMxJGX1qhRKTexBgMf"
}

Manifest reference

* denotes mandatory fields

  • app_type * - always APP
  • app_title * - title of App, non-localizable string
  • app_icon * - link to App icon image, square, at least 80 x 80 px
  • app_version * - version number in format x.x.x
  • app_display_title - string or languages object, use if your title is localizable
  • app_description_short * - string or languages object, text must be very brief
  • app_description_full * - string or languages object
  • app_screenshots - string or languages object, links to images, one screenshot per language
  • app_vendor * - info about the App developer
    • company_name * - name of representing company
    • support_email * - support e-mail, string or langages object
    • support_phone * - support phone number, string or languages object
    • developer_email * - e-mail for informing about critical and breaking API changes
    • company_url * - link to company website, string or languages object
    • support_url * - link to App support website, string or languages object
    • privacy_url * - link to Privacy Policy page, string or languages object
    • tos_url * - link to Terms of Service page, string or languages object
  • app_permissions * - always ["FULL"]
  • app_tab_mode * - blank or self. Use blank to open your App in new tab or self for the same tab
  • app_install_url * - link to App installation process initialization
  • app_settings_url * - link to App configuration, management or main panel
  • app_secret * - secret string used for verifying App requests from Mozello; think of this as a password, it is made up by you, you can use something you can easily remember or a random string

Implementing App installation

When Mozello user installs App to their website, they will get redirected to your App installation link. Your App must perform specific steps to complete the installation process successfully.

Steps:

  1. Prerequisite: App must be added to Mozello App catalog
  2. User clicks Install button in Mozello App catalog
  3. App installation link loads (as specified in App manifest)
  4. App must verify the request hash
  5. App must use callback parameter and add all GET parameters except callback and hash to obtain redirect link. Perform the redirect
    Example
    For request link:
    https://www.example.org/helloworld/install.php?callback=https%3A%2F%2Fexample&hash=12345abcd&appId=1234567890&language=en
    Corresponding Mozello installation initialization link is:
    https://example?appId=1234567890&language=en
  6. User must review the App permission request screen and click Accept
  7. App installation link loads again but this time authCode parameter is set. You will need authCode to call API functions. If your App has users, you can associate authCode with the user
  8. App must verify the request hash again
  9. App must use installed method from Apps API to finish the installation process
  10. App can be displayed. Alternatively, redirect back to Mozello (for Apps with app_tab_mode set to self). To redirect user back to Mozello, use callback parameter and add all GET parameters except callback and hash to obtain redirect link. Perform the redirect

Request parameters

  • hash - must be used to verify request authenticity
  • authCode - code that specifies the Mozello App installation instance and must be used for Apps API authentication
  • appId - Mozello App ID in Mozello Apps catalog
  • language - preferred UI language for user
  • callback - link for returning to Mozello
  • mozelloVersion - Mozello frontend version number

Implementing App configuration

For already installed App, user can click Settings button. This will open settings link, which should point to App configuration, management or the main panel of the App.

For this request authCode parameter is included, which lets your App know that the user has been authenticated with Mozello and if you associated this authCode with user in your App during installation, you can log in the user automatically.

Steps:

  1. User clicks Settings button in Mozello App catalog
  2. App settings link loads (as specified in App manifest)
  3. App must verify the request hash
  4. App can be displayed. Use Apps API or Store API where appropriate to interact with Mozello website

Request parameters

  • hash - must be used to verify request authenticity
  • authCode - code that specifies the Mozello App installation instance and must be used for Apps API authentication
  • appId - Mozello App ID in Mozello Apps catalog
  • language - preferred UI language for user
  • callback - link for returning to Mozello
  • mozelloVersion - Mozello frontend version number

Verifying request authenticity

Installation and settings requests must be verified to ensure that they are coming from Mozello.

The hash is computed by running a sha256 HMAC hash function on the query string of the request for all parameters except hash. Use app_secret specified in App manifest as hash function key.

Pseudo code for generating signature

query_string_truncated = remove_parameter("hash", query_string)
signature = HMAC_SHA256(query_string_truncated, secret)

PHP example for validating request

if (isset($params['hash'])) {
    unset($params['hash']);
}

$params = http_build_query($params);
$calculatedHash = hash_hmac('sha256', $params, $secret); // $secret is app_secret from app manifest

// check if hash matches
if ($hash == $calculatedHash) {
    // Your code here
}

Sample source code

This sample demonstrates the basic framework for App and implements the installation, configuration and verification steps described above: mozello-sample-app-hello-world on GitHub