

App Publishing API Contents¶

This API documentation is useful for who wants to publish own edge application releases in Insights Hub.

Each Application Product can have multiple Application Releases. An Application Release has a unique version number and a set of artifacts as well as additional metadata such as release notes, terms and condition documents, etc.

An Application “release” is tied to set of firmware releases, i.e. can only be installed on devices which contain specific firmware release. An application release can be compatible with multiple firmware releases.

Each application release has one or more artifacts. Artifacts are stored in a special file storage system that is optimized for serving large files to many devices simultaneously. Artifacts can be uploaded / downloaded directly from this storage system by using URIs with embedded security credentials. The API offers endpoints for generating such URIs for upload and download.

Publishing an edge application, app owner must need to follow the steps with given order.

Note

Required parameters are X-XSRF-TOKEN, Cookie (ex: Cookie: SESSION=<SESSION>;XSRF-TOKEN=<XSRF-TOKEN>;REGION-SESSION=<REGION-SESSION>) must be taken from App Publishing (MindApp is edgeapppublish) application.

Get Application with Application ID¶

Get a application with application id.

Request: GET

/apppublishapi/apps/

Headers:
Body:
Result:

{
 "id": "<app_id>",
 "name": "<application_name>",
 "description": "<application _description>",
 "owner": "<tenant>"
}

Get Application with Application Name¶

Get a application with application name.

Request: GET

/apppublishapi/apps?appName=

Headers:
Body:
Result:

{
 "id": "<app_id>",
 "name": "<application_name>",
 "description": "<application _description>",
 "owner": "<tenant>"
}

Create Application¶

Create a new application.

Request: POST

/apppublishapi/apps

Headers:

Content-Type: application/json

Body:

{
 "name": "<application_name>",
 "description": "<application _description>"
}

Result:

{
 "id": "<app_id>",
 "name": "<application_name>",
 "description": "<application _description>",
 "owner": "<tenant>"
}

Create Application Release¶

Create a new application release.

Request:

/apppublishapi/apps/<app_id>/releases

Headers:

Content-Type: application/json

Body:

{
 "name": "<app_release_name>",
 "softwareVersion": "<app_release_version>",
 "description": "<app_release_description>",
 "compatibleFirmwareReleaseIds": ["<firmware_id>"]
}

Result:

{
 "name": "<app_release_name>",
 "softwareVersion": "<app_release_version>",
 "description": "<app_release_description>",
 "compatibleFirmwareReleaseIds": ["<firmware_id>"]
}

Add Application Artifact¶

Add artifact to application release.

Request: POST

/apppublishapi/apps/<app_id>/releases/<app_release_id>/artifacts

Headers:

Content-Type: application/json

Body:

{
 "checksum": "<artifact_sha1sum>",
 "name": "<artifact_name>"
}

Result:

{
 "id": "<app_id>",
 "softwareId": "<app_release_id>",
 "softwareVersion": "<app_release_version>",
 "name": "<app_release_name>",
 "description": "<app_release_description>",
 "artifacts": [
    {
     "id": "<artifact_id>",
     "name": "<artifact_name>",
     "checksum": "<artifact_sha1sum>"
    }
 ],
 "termsAndConditions": null,
 "releaseNotes": null,
 "status": "CREATED",
 "compatibleFirmwareReleaseIds": null,
 "publishedDate": null
}

Generate Artifact Upload URI¶

Generate artifact upload URI.

Request: POST

/apppublishapi/apps/<app_id>/releases/<release_id>/artifacts/<artifact_id>/upload

Headers:

Content-Type: application/json

Body:

{
 "size": <artifact_size>
}

Result:

{
 "uri": "<artifact_upload_uri>",
 "validUntil": "2020-01-11T10:5:15.723Z"
}

PUT Application Release Artifact¶

Upload artifact into cloud memory storage.

Request: PUT

<artifact_upload_uri>

Headers:

Content-Length: <artifact_size>

x-amz-acl: bucket-owner-full-control

x-amz-content-sha256: <artifact_sha256sum>

Body:

Select file from local

Result:

200 OK

Upload Document (Terms & Conditions and Release Notes Documents)¶

Both Terms & Conditions and Release Notes are a bundle. They have identical bundle creation structure and upload documentation. Only differences is attaching bundle to application release endpoint (Terms & Conditions is end with /termsandconditions, Release Notes is end with /releasenotes).

Create Bundle¶

Create bundle with multiple documents.

Request: POST

/apppublishapi/bundles

Headers:

Content-Type: application/json

Body:

{
 "author": "<author_name>",
 "desc": "<bundle_description>",
 "documents": [
    {
     "name": "<document_name>",
     "description": "<document_description>",
     "language": "<language>",
     "type": "<file_type>"
    }
 ]
}

Result:

{
 "id": "<bundle_id>",
 "description": "<bundle_description>",
 "rowVersion": null,
 "documents": [
      {
        "id": "<document_id>",
        "language": "<language>",
        "name": "<document_name>",
        "description": "<document_description>",
        "uri": "<document_upload_uri>",
        "rowVersion": null,
        "validUntil": "2020-01-06T11:34:12.060Z",
        "type": "<file_type>"
      }
 ]
}

Upload Document¶

Upload document into cloud memory storage.

Request: PUT

<document_upload_uri>

Headers:

x-amz-acl: bucket-owner-full-control

x-amz-content-sha256: <document_sha256sum>

Body:

Select document from local

Result:

200 OK

Attach Terms & Conditions and Release Notes to Application Release¶

Attaching bundle as Terms & Conditions or Release Notes to related application release with following endpoints.

Attach Terms & Conditions¶

Request: POST

/apppublishapi/apps/<app_id>/releases/<release_id>/termsandconditions

Headers:

Content-Type: application/json

Body:

{
 "documentId": "<bundle_id>"
}

Result:

{
 "id": "<app_release_id>",
 "softwareId": "<app_id>",
 "softwareVersion": "<app_release_version>",
 "name": "<app_release_name>",
 "description": "<app_release_description>",
 "artifacts": [
      {
        "id": "<app_release_artifact_id>",
        "name": "<app_release_artifact_name>",
        "checksum": "<artifact_sha1sum>"
      }
   ],
 "termsAndConditions": "<bundle_id>",
 "releaseNotes": null,
 "status": "CREATED",
 "compatibleFirmwareReleaseIds": null,
 "publishedDate": null
}

Attach Release Notes¶

Request: POST

/apppublishapi/apps/<app_id>/releases/<release_id>/releasenotes

Headers:

Content-Type: application/json

Body:

{
 "documentId": "<bundle_id>"
}

Result:

{
 "id": "<app_release_id>",
 "softwareId": "<app_id>",
 "softwareVersion": "<app_release_version>",
 "name": "<app_release_name>",
 "description": "<app_release_description>",
 "artifacts": [
      {
        "id": "<app_release_artifact_id>",
        "name": "<app_release_artifact_name>",
        "checksum": "<artifact_sha1sum>"
      }
   ],
 "termsAndConditions": null,
 "releaseNotes": "<bundle_id>",
 "status": "CREATED",
 "compatibleFirmwareReleaseIds": null,
 "publishedDate": null
}

PUT Metadata¶

Create or updates whole metadata configuration.

Note: Required metadata fields for all metadata configs are ‘system_service:boolean’, ‘version:string’, ‘configVersion:string’ and ’lifecycleConfig:object’

Request: PUT

/apppublishapi/apps/<app_id>/releases/<app_release_id>/metadata

Headers:

Content-Type: application/json

Body:

<metadata_config.json>

Result:

<metadata_config.json>

Publish Application Release¶

Publishing the application and document for application release.

Request: POST

/apppublishapi/apps/<app_id>/releases/<app_release_id>/publish

Headers:

Content-Type: application/json

Body:
Result:

{
 "id": "<app_release_id>",
 "softwareId": "<app_id>",
 "softwareVersion": "<app_release_version>",
 "name": "<app_release_name>",
 "description": "<app_release_description>",
 "artifacts": [
      {
        "id": "<app_release_artifact_id>",
        "name": "<app_release_artifact_name>",
        "checksum": "<artifact_sha1sum>"
      }
   ],
 "termsAndConditions": "<terms_and_conditions_bundle_id>",
 "releaseNotes": "<release_notes_bundle_id>",
 "status": "PUBLISHED",
 "compatibleFirmwareReleaseIds": [],
 "publishedDate": null
}

Delete Application¶

Delete application from application list.

Request: DELETE

/apppublishapi/apps/<app_id>

Headers:
Body:
Result:

204 OK

Delete Application Release¶

Delete application release from application release list.

Request: DELETE

/apppublishapi/apps/<app_id>/releases/<app_release_id>

Headers:
Body:
Result:

204 OK

Any questions left?

Ask the community

Except where otherwise noted, content on this site is licensed under the The Siemens Inner Source License - 1.1.