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>
http

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>
http

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"]
}
http
Response (success)
HTTP/1.1 303 See other
Location: resources/apps/myApp
http
Response (error)
HTTP/1.1 400
Content-Type: application/json

{
    "code": 0,
    "error": "error message here"
}
json
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
http
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"]
    }]
}
http
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
http
Response (success)
HTTP/1.1 200 OK
Content-Type: text/html

HTML content here
http

Get app meta data

Returns the meta data of an app.

Request
GET resources/apps/{appId}
http
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"]
}
http

Redirect to index.html of app

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

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

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"],
}
http
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"]
}
http
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}
http
Response (success)
HTTP/1.1 204 No Content
http

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--
http
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

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

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

Get the app.json

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

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

{
    // app configuration here
}
http
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
}
http
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{ "success": true }
http

Launch app

Launches an app.

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

HTML content here
http

Get thumbnail

Returns the thumbnail of an app.

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

(binary data)
http

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}
http
Response (success)
HTTP/1.1 200 OK
Content-Type: image/png

(binary data)
http

Get array with resource names

Returns a json array with all resources of an app.

Request
GET resources/apps/{appId}/$raw/$index
http
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"]
http

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}
http
Response (success)
HTTP/1.1 200 OK
Content-Type: image/png

(binary data)
http

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...
http
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

{ "success": true }
http

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--
http
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

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

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

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}
http
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

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

Get app meta data

Returns the meta data of an app.

Request
GET resources/apps/{appId}.json
http
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"]
}
http

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}
http
Response (success)
HTTP/1.1 200 OK
Content-Type: application/octet-stream

(binary data)
http
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}
http
Response (success)
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="myApp.zip"
Content-Length: 12345

<binary data>
http
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}
http
Response (success)
HTTP/1.1 200 OK
Content-Type: application/json

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

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

preoptimized

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