App Management REST interface

The base endpoint of the App Management is http://<server>:<port>/<contextname>/resources/apps.

Authentication

Authentication is required for all endpoints. The actual type required depends on how the security mode is configured in map.apps.

Basic Authentication

If map.apps uses the INTEGRATED or ONLY_AUTHN security mode, you could use HTTP Basic Authentication to provide credentials.

Request
GET resources/apps
Authentication: Basic <base64 encoded username:password>

Authentication via Access Token

If map.apps uses security mode IDENTITY to use an external identity provider like Keycloak for authentication, you could use HTTP Bearer Authentication to provide an access token.

Request
GET resources/apps
Authentication: Bearer <access_token>

The Identity Service itself provides a tokens endpoint to retrieve access tokens.

Endpoints

METHOD RESOURCE DESCRIPTION

POST

resources/apps

Create app

GET

resources/apps

Query existing apps

GET

resources/apps/index.html

Get app overview page

GET

resources/apps/{appId}

Get app meta data

GET

resources/apps/{appId}

Redirect to index.html of app

PUT

resources/apps/{appId}

Update app meta data

DELETE

resources/apps/{appId}

Delete app

POST

resources/apps/{appId}

Upload app

GET

resources/apps/{appId}/app.json

Get the app.json

PUT

resources/apps/{appId}/app.json

Update app configuration

GET

resources/apps/{appId}/index.html

Launch app

GET

resources/apps/{appId}/thumbnail.png

Get thumbnail

GET

resources/apps/{appId}/{resourcePath}

Get resource

GET

resources/apps/$raw/$index

Get array with resource names

GET

resources/apps/{appId}/$raw/{resourcePath}

Get resource

PUT

resources/apps/{appId}/$raw/{resourcePath}

Create resource

POST

resources/apps/{appId}/$raw/{resourcePath}

Upload resource

DELETE

resources/apps/{appId}/$raw/{resourcePath}

Delete resource

GET

resources/apps/{appId}.json

Get app meta data

GET

resources/apps/{appId}.zip

Export app using GET

POST

resources/apps/{appId}.zip

Export app using POST

POST

resources/apps/{appId}/preoptimizedState

Enable or disable app pre-optimization

Create app

Allows to create an app. Some data about the app must be provided in the request body, e.g. the ID and the title.

Request
POST resources/apps
Content-Type: application/json

{
    "id": "myApp",
    "title": "My App",
    "description": "My App Description",
    "sharedInGroups": ["maAdmin"]
}
Response (success)
HTTP/1.1 303 See other
Location: resources/apps/myApp
Response (error)
HTTP/1.1 400
Content-Type: application/json

{
    "code": 0,
    "error": "error message here"
}
Request JSON
Name Default Description

id

The ID of the new app.

title

The title for the app.

description

''

Optional. The description for the app.

sharedInGroups

[]

Optional. The groups the app is shared with. Empty array means the app is shared with everyone.

templateId

Optional. The id of template the app should be based on. The templateId can be obtained by querying the resources/templates endpoint of map.apps.

Query existing apps

Allows to query existing apps. Depending on the Accept-Header the result is returned as JSON or HTML.

Request
GET resources/apps?filter=(and title="My App";createdBy="admin")
accept: application/json
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{
    "total":1,
    "items":[{
        "editorState": "PUBLISHED",
        "preoptimized": false,
        "id": "myApp",
        "title": "My App",
        "description": "My App Description",
        "createdBy": "admin",
        "createdAt": 1702647666749,
        "modifiedBy": "admin",
        "modifiedAt": 1702648738184,
        "templateId": "",
        "templateFile": "",
        "thumbnailFile": "",
        "sharedInGroupsCount": 0,
        "portalItemStatus": "",
        "sharedInGroups": ["maAdmin"]
    }]
}
Query Parameters
Name Default Description

filter

Optional. A filter query expression that allows to search for apps by its properties.

Simple Query:

<property>=<value>, for example title="My App" or createdBy="admin"

Simple Queries can be combined using and, or, not operators like:

(and title="My App";createdBy="admin") which means: return app with title My App created by admin.

Wildcards:

To filter all apps starting with A you could use the following filter: title like "A*".

sort

+title

Optional. A comma separated list of property names prefixed by + or -, which defines the sort order of the response, for example:

+title,-id, for example, sorts based on the title property (ascending) and then remaining equal items after the ID (descending).

range

0-

Optional. This is a range expression to allow paging through the result list.

The formal definition of the range expression is: <startindex>-<endindex>.

0- = return all results

0-0 = return the first item

0-1 = return the first two items of the result set

10-12 = return the 10th, 11th, 12th item

0—​1 = return nothing (only return the count)

edit

false

Optional. If true, the result contains only those apps, which are editable by the current user.

f

html

Optional. json to force json result.

Get app overview page

Returns the app overview page.

Request
GET resources/apps/index.html
Response (success)
HTTP/1.1 200 OK
Content-Type: text/html

HTML content here

Get app meta data

Returns the meta data of an app.

Request
GET resources/apps/{appId}
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{
    "editorState": "PUBLISHED",
    "preoptimized": false,
    "id": "myApp",
    "title": "My App",
    "description": "My App Description",
    "createdBy": "admin",
    "createdAt": 1702647666749,
    "modifiedBy": "admin",
    "modifiedAt": 1702648738184,
    "templateId": "",
    "templateFile": "",
    "thumbnailFile": "",
    "sharedInGroupsCount": 0,
    "portalItemStatus": "",
    "sharedInGroups": ["maAdmin"]
}

Redirect to index.html of app

Redirects the browser to the index.html of the app.

Request
GET resources/apps/{appId}
accept: text/html
Response (success)
HTTP/1.1 303 See other
Location: resources/apps/{appId}/index.html

Update app meta data

This endpoint allows to update the meta data of apps. The app is identified by its ID.

Request
PUT resources/apps/{appId}
Content-Type: application/json

{
    "id": "myApp",
    "title": "My App",
    "description": "My App Description",
    "editorState": "PUBLISHED",
    "sharedInGroups": ["maAdmin"],
}
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{
    "editorState": "PUBLISHED",
    "preoptimized": false,
    "id": "myApp",
    "title": "My App",
    "description": "My App Description",
    "createdBy": "admin",
    "createdAt": 1702647666749,
    "modifiedBy": "admin",
    "modifiedAt": 1702648738184,
    "templateId": "",
    "templateFile": "",
    "thumbnailFile": "",
    "sharedInGroupsCount": 0,
    "portalItemStatus": "",
    "sharedInGroups": ["maAdmin"]
}
Request JSON Content
Name Description

id

The id of the app.

title

The new title for the app. If empty the title is set to an empty string.

description

The new description for the app. If empty the title is set to an empty string.

editorState

Optional. The new state of the app. Allowed values are 'DRAFT', 'EDITED', 'VERIFIED', 'PUBLISHED' AND 'DEPRECATED'.

sharedInGroups

Optional. The groups the app is now shared with. Empty array means the app is shared with everyone.

Delete app

Deletes an app by its id.

Request
DELETE resources/apps/{appId}
Response (success)
HTTP/1.1 204 No Content

Upload app

Allows to upload an archive containing the app content. The current app will be replaced by the content of the uploaded archive.

Request
POST resources/apps/{appId}
Content-Type: multipart/form-data; boundary=------BOUNDARY

------BOUNDARY
Content-Disposition: form-data; name="file"; filename="myApp.zip"
Content-Type: application/zip

<BINARY DATA HERE>
------BOUNDARY--
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{
  "file": "myApp.zip",
  "name": "file",
  "type": ".zip"
}
Response (error)
HTTP/1.1 200 OK
Content-Type: application/json

{
  "file": "myApp.zip",
  "name": "file",
  "type": ".zip",
  "error": "error message here"
}

Get the app.json

Returns the content of the app.json of an app.

Request
GET resources/apps/{appId}/app.json
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{
    // app configuration here
}
Query Parameters
Name Default Description

preview

false

If true, wizard (or preview) bundles are contained in the result.

autorefresh

0

If value is present and greater then 0, autorefresh bundles are contained in the result.

Update app configuration

This endpoint allows to update the configuration of the app (content of the app.json).

Request
PUT resources/apps/{appId}/app.json
Content-Type: application/json

{
    // app configuration here
}
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{ "success": true }

Launch app

Launches an app.

Request
GET resources/apps/{appId}/index.html
Response (success)
HTTP/1.1 200 OK
Content-Type: text/html

HTML content here

Get thumbnail

Returns the thumbnail of an app.

Request
GET resources/apps/{appId}/thumbnail.png
Response (success)
HTTP/1.1 200 OK
Content-Type: image/png

(binary data)

Get a resource

Returns any resource contained in the app identified by its path. The path parameter resourcePath points to a resource inside the app for example images/logo.png.

Request
GET resources/apps/{appId}/{resourcePath}
Response (success)
HTTP/1.1 200 OK
Content-Type: image/png

(binary data)

Get array with resource names

Returns a json array with all resources of an app.

Request
GET resources/apps/{appId}/$raw/$index
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

["app.json","thumbnail.png","images/hybrid.png","images/logo_conterra.png","images/topo.png","images/streets.png","nls/bundle.js.map","nls/bundle.js","nls/de/bundle.js.map","nls/de/bundle.js"]

Get resource

Returns any resource contained in the app identified by its path. The path parameter resourcePath points to a resource inside the app for example images/logo.png.

Request
GET resources/apps/{appId}/$raw/{resourcePath}
Response (success)
HTTP/1.1 200 OK
Content-Type: image/png

(binary data)

Create resource

Allows to create a new resource for an app. This is typically used to initially create new app resources.

Request
PUT /resources/apps/{appId}/$raw/{resourcePath}
content-type: text/plain

Enter content...
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{ "success": true }

Upload resource

Allows to upload resources to the app. Might be used to upload content for new or existing app resources.

Request
POST resources/apps/{appId}/$raw/{resourcePath}
Content-Type: multipart/form-data; boundary=------BOUNDARY

------BOUNDARY
Content-Disposition: form-data; name="file"; filename="example.png"
Content-Type: image/png

<BINARY DATA HERE>
------BOUNDARY--
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{
  "file": "example.png",
  "name": "file",
  "type": ".png"
}
Response (error)
HTTP/1.1 200 OK
Content-Type: application/json

{
  "file": "example.png",
  "name": "file",
  "type": ".png",
  "error": "error message here"
}

Delete resource

Allows to delete a resource of an app. The path parameter resourcePath points to a resource inside the app for example images/logo.png.

Request
DELETE /resources/apps/{appId}/$raw/{resourcePath}
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{ "success": true }
Response (error)
HTTP/1.1 404 Not found

Get app meta data

Returns the meta data of an app.

Request
GET resources/apps/{appId}.json
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{
    "editorState": "PUBLISHED",
    "preoptimized": false,
    "id": "myApp",
    "title": "My App",
    "description": "My App Description",
    "createdBy": "admin",
    "createdAt": 1702647666749,
    "modifiedBy": "admin",
    "modifiedAt": 1702648738184,
    "templateId": "",
    "templateFile": "",
    "thumbnailFile": "",
    "sharedInGroupsCount": 0,
    "portalItemStatus": "",
    "sharedInGroups": ["maAdmin"]
}

Export app using GET

Exports the app content as a zip archive. Its also possible to export the app as standalone app by setting the standalone query parameter to true.

Request
GET resources/apps/{appId}.zip?standalone={true|false}
Response (success)
HTTP/1.1 200 OK
Content-Type: application/octet-stream

(binary data)
Query Parameters
Name Default Description

standalone

false

Optional. true, to export a standalone app. false to export app resources as zip archive.

customLayerModules

Optional. Comma separated list of custom layer modules.

customFiles

Optional. Comma separated list of custom files.

Export app using POST

Exports the app content as a zip archive. Its also possible to export the app as standalone app by setting the standalone form parameter to true.

Request
POST resources/apps/{appId}.zip
Content-Type: application/x-www-form-urlencoded

standalone={true|false}
Response (success)
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="myApp.zip"
Content-Length: 12345

<binary data>
Form Parameters
Name Default Description

standalone

false

Optional. true, to export a standalone app. false to export app resources as zip archive.

customLayerModules

Optional. Comma separated list of custom layer modules.

customFiles

Optional. Comma separated list of custom files.

Enable or disable pre-optimization

Enables or disables pre-optimization of an app. This operation might take a while to complete.

Request
POST resources/apps/{appId}/preoptimizedState?preoptimized={true|false}
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}
Response (error)
HTTP/1.1 500 OK
Content-Type: application/json

{
    "code": 500,
    "error": "error message here"
}
Query Parameters
Name Default Description

preoptimized

true, to enable pre-optimization. false to disable it.