Qt Automotive Suite Deployment Server API Reference

API Reference

The following tables describe the requests, their parameters, as well as the corresponding responses.

hello

Checks whether you are using the correct Platform and the right API to communicate with the deployment server.

ParameterDescription
platformThe platform on which the client is running. This parameter sets the architecture of the packages you get. For more information, refer to the settings.APPSTORE_PLATFORM parameter in the appstore/settings.py file.
versionThe Deployment Server's HTTP API version that you are using to communicate with the server. For more information, see settings.APPSTORE_VERSION.
require_tag (can also be passed as tag )An optional parameter used to filter packages by tags. Receives a comma-separated list of tags; these tags must be alphanumeric. Only applications that match any of the specified tags (and not matching those in their conflicts list should be listed).
architectureAn optional parameter used to filter packages by architecture. Receives the CPU architecture. If the architecture is not speciifed, only packages showing All architecture are listed.

Returns a JSON object with the following fields and values.

JSON FieldValueDescription
statusokSuccessful
maintenanceThe server is in maintenance mode and cannot be used at the moment.
incompatible-platformThe platform you are using is not compatible.
incompatible-versionThe API version you are using is not compatible.
incompatible-architectureThe architecture parameter was malformed, or server was unable to parse it.
malformed-tagThe tag format is incorrect, may not be alphanumeric, or could not be parsed.

login

Logs onto the Deployment Server with the given username and password. Either an IMEI or a unique hardware identifier, such as a MAC address, must be provided. This call is necessary to be able to download apps.

ParameterDescription
usernameThe username.
passwordThe password for the specified username.

Returns a JSON object with the following fields and values.

JSON FieldValueDescription
statusokLogin successful.
missing-credentialsNo username or password was provided.
account-disabledThe account has been disabled in the Admin panel.
authentication-failedThe user name and/or password may be wrong; or another authentication error occurred.

logout

Logs out the currently logged-in user from the Deployment Server.

Returns a JSON object with the following fields and values.

JSON FieldValueDescription
statusokThe user has logged out successfully.
failedThe user was not logged in.

app/list

Lists all apps. The returned list can be filtered by using the category_id and the filter parameters.

ParameterDescription
category_idLimits the app to those with this category ID only.
filterLists apps with names that match this filter only.

Returns an array of JSON objects (not an object itself!).

JSON FieldDescription
idA unique app ID, in reverse domain name notation.
nameThe app's name.
vendorThe vendor name for the app; not the vendor ID.
categoryA category name for the app.
tagsJSON array of tags required for the app
conflict_tagsJSON array of tags which will conflict with the app
versionThe app's version, returned as a string. If the there is no version number, the default version, "0.0.0" is returned.
architectureThe app's architecture, returned as detected in the app's library components.

If the application is not native, contains All. Otherwise it is formed like this: mips-little_endian-32-elf

Where it is a combination of:

  1. CPU architecture, as returned by QsysInfo::buildCpuArchitecture()
  2. CPU endianness, either little_endian or big_endian)
  3. ABI bitness
  4. Binary format, either elf, mach_o or pe32
briefDescriptionA short text that describes the app, limited to 1 line, approximately 80-130 characters.
category_idNumeric category ID that matches the app's category.
purchaseIdPurchase identifier, freeform identifier of specific application on the server. Used as an alternative to ID in app/purchase API call. This is a freeform string, currently a UUID, but no assumptions should be made of the format.
iconUrlURL for the icon of this application

app/icon

Returns an icon for the given application id.

ParameterDescription
idThe app ID.
architectureAn optional parameter used to filter icons by architecture. Overrides architecture specified in session. Receives the CPU architecture. If architecture was not specified either in session or in this parameter, only icons showing All architecture are listed.

Returns a PNG image if the app exists; an HTTP 404 error otherwise.

app/description

Returns a description for the given app ID.

ParameterDescription
idapp ID

Returns a description text for the app, either HTML or plain text.

app/purchase

Returns a URL that you can use to download the requested app for a certain period of time only; configurable in the settings.

Note: This request is a legacy from the AppStore. Changing the name of this API would involve changes in Neptune 3 UI.

ParameterDescription
device_idA unique device ID for the client hardware; currently not used.
idThe app ID.
purchaseIdAlternative app ID, to select specific app with tags and all (see app/list API description). If both ID and purchaseId are specified, ID takes precedence.

Returns a JSON object:

JSON FieldValueDescription
statusokSuccessful
failedAn error has occurred, check the error field for more information.
errorText.If the status is equal to failed, contains an error description.
urlA URL.The URL from where to download the app. Expires according to the value specified in expiresIn.
expiresInAn integer value.Time in seconds during which the download URL is valid.

category/list

Lists all of the available categories. Also returns the All metacategory, that is used to hold all available applications.

Returns an array of JSON objects (not an object itself!).

JSON fieldDescription
idUnique category id.
nameCategory name.

category/icon

Returns an icon for the given category ID.

ParameterDescription
idThe category ID.

Returns an image in PNG format or an empty 1x1 PNG file.

Note: Currently takes the icon of the first app in the category, if it exists.

upload

Accepts remote package upload requests. The user must be in the staff group to use this API. Also requires either basic authentication or a previous call to the login method. This is a POST request to the server due to the parameters used.

ParameterDescription
descriptionPackage description, long version. Can be text or HTML.
short-descriptionOne line package description.
categoryCategory name for the category where the package will be put.
vendorVendor name for the package.
packagePackage itself. This is uploaded as a file parameter.

Returns JSON object:

ParameterValueDescription
statusokSuccess
no descriptionThe description parameter is missing.
no short descriptionThe short-description parameter is missing.
no categoryThe category parameter is missing.
no vendorThe vendor parameter is missing.
Package validation failedPackage did not pass format or sanity validation
Non-existing categoryThe specified category does not match the parameter passed.
Non-existing vendorThe specified vendor does not match the parameter passed.
no package to uploadThere was no package parameter in the request, or it was not a POST request.

API Usage Examples

The Deployment Server exposes an HTTP API. Arguments to these requests need to be provided using the HTTP GET or POST syntax. The data is returned in JSON, PNG, or text format, depending on the request.

Workflow

  1. Send a hello request to the server to get the current status and to check whether your platform is compatible with this server instance:

    http://<server>/hello?platform=AM&version=1

    Returns:

    { "status": "ok" }

  2. Login as user with password, pass:

    http://<server>/login?username=user&password=pass

    Returns:

    { "status": "ok" }

  3. List all applications

    http://<server>/app/list

    Returns:

    [{ "category": "Entertainment", "name": "Nice App", "vendor": "Luxoft", "briefDescription": "Nice App is a really nice app.", "category_id": 4, "id": "com.luxoft.niceapp"}, .... ]

  4. Request a download for an app:

    http://<server>/app/purchase?device_id=12345&id=com.luxoft.niceapp

    Returns:

    { "status": "ok", "url": "http://<server>/app/download/com.luxoft.niceapp.2.npkg", "expiresIn": 600 }

  5. Use the url provided in step 4 to download the application within expiresIn seconds.

© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.