Package Tree REST Interface

The service endpoint of the package tree interface of the JS Registry is http://<server>:<port>/<contextname>/resources/jsregistry/root. This REST interface is an implementation of a CommonJS Compliant Package Registry . This is the main interface used by the map.apps JavaScript API to locate and load bundles.

Browse Packages

List all available package names

Requesting the root URL returns the list of all package names registered in the registry. Each entry links to the package root inside the registry.

Request
GET /resources/jsregistry/root
Response
{
    "aceeditor": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/aceeditor",
    "esri": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/esri",
    "map": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/map",
    "xstyle": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/xstyle"
}

List all versions of a package

To list all version of a concrete package the package name is added to the root URL. The response lists all available versions of the package. The dist-tags section shows the latest version.

Request
GET /resources/jsregistry/root/{name}
Response
//GET /resources/jsregistry/root/map
{
    "name": "map",
    "dist-tags": {
        "latest": "3.1.0-SNAPSHOT"
    },
    "versions": {
        "3.1.0-SNAPSHOT": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/map\/3.1.0-SNAPSHOT",
        "3.0.9": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/map\/3.0.9"
    }
}

Show metadata of an exact version of a package (package.json)

The metadata of a package can be accessed by adding its name and version to the root URL of the registry. The response is the package.json of the very package.

Request
GET /resources/jsregistry/root/{name}/{version}
Response
//GET /resources/jsregistry/root/map/3.1.0-SNAPSHOT
{
    "name": "map",
    "version": "3.1.0-SNAPSHOT",
    "title": "Map",
    "description": "The Map bundle manages the main map and all map content information...",
    "vendor": "con terra GmbH",
    "Config-Bundle-Location": "/config",
    "startLevel": 40,
    "layer": "module",
    "main": "main",
    "i18n": ["bundle"],
    "optionalDependencies": {
        "coordinatetransformer": ">=3.1.0-SNAPSHOT"
    },
    "components": [...],

    // two special properties
    "_id": "map@3.1.0-SNAPSHOT",
    "location": "http:\/\/localhost:8080\/js\/bundles\/mapcore\/map"
}

The _id property defines the internal package ID in the context of the registry.

The location property contains a link to the URL from which the package resources can be resolved.

Access a package resource

It is possible to access a file inside a package by adding the file path to the exact package path.

Request
GET /resources/jsregistry/root/{name}/{version}/{file}
Response
//GET /resources/jsregistry/root/map/3.1.0-SNAPSHOT/module.js

<<Binary data of the file requested>>

The registry supports pre-compressed gzip and Brotli assets. If a resource like /custom.pdf is requested then the registry checks for existing pre-compressed versions of the requested file e.g. /custom.pdf.gz for gzip and /custom.pdf.br for Brotli. If one of the files exist it is directly delivered to the client according to the accept-encoding HTTP header.

Advanced Package Queries

Search for packages

The root endpoint provides a filter parameter, which can be used to query for packages inside the registry.

Request - Search all packages starting with 'a'
GET /resources/jsregistry/root?filter=name%20like%20"a*"
Response
{
    "aceeditor": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/aceeditor",
    "addthis": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/addthis",
    "agolauthn": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/agolauthn",
    "agolmapfinder": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/agolmapfinder",
    "agsprinting": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/agsprinting"
}
Query Parameter
Name Default Description

filter

A filter query expression that allows to search for packages with special properties.

Simple Query:

<property>=<value>, for example name="map" or title="test" or version="3.1.0"

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

(and version="3.1.0";title like "d*") which means: return packages with version 3.1.0 and title starting with the character d.

Inline package versions

The root endpoint provides a versions parameter, which can be used to include versions in the packages response.

Request - Search all packages starting with 'a' and include the version information
GET /resources/jsregistry/root?filter=name%20like%20"a*"&versions=true
Response
{
    "aceeditor": {
        "name": "aceeditor",
        "dist-tags": {
            "latest": "3.1.0-SNAPSHOT"
        },
        "versions": {
            "3.1.0-SNAPSHOT": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/aceeditor\/3.1.0-SNAPSHOT",
            "3.0.9": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/aceeditor\/3.0.9"
        }
    },
    ...
}
Query Parameter
Name Default Description

versions

false

Enables including versions

Inline package info

The root endpoint provides a inline parameter, which can be used to embed version and packages info in the packages response.

Request - Search all packages starting with 'a' and embed the package info
GET /resources/jsregistry/root?filter=name%20like%20"a*"&inline=true
Response
{
    "aceeditor": {
        "name": "aceeditor",
        "dist-tags": {
            "latest": "3.1.0-SNAPSHOT"
        },
        "versions": {
            "3.1.0-SNAPSHOT": {
                "name": "aceeditor",
                "ACE-VERSION": "1.1.1",
                "version": "3.1.0-SNAPSHOT",
                "title": "ACE Editor",
                "description": "The ACE Editor provides a code editor.",
                "keywords": ["code"],
                "url": "http://ace.c9.io/",
                "layer": "module",
                "main": "main",
                "i18n": ["bundle"],
                "components": [...],
                "_id": "aceeditor@3.1.0-SNAPSHOT",
                "location": "http:\/\/localhost:8080\/js\/bundles\/base\/aceeditor"
            },
            "3.0.9" : {
                ...
            }
        }
    },
    ...
}
Query Parameter
Name Default Description

inline

false

Enables inlining package info

Required Packages Resolution

The following clause describes different options of fetching package information if required by an application.

Consider that all requests being described result in a package list with exactly one version per package. The calculated versions are the best matching ones for the requirements previously being declared.

Fetch packages info from packages.json

This endpoint is provided to fetch the meta information required to register packages in an AMD loader. The response can be directly used to configure the Dojo AMD loader.

Request
GET /resources/jsregistry/root/packages.json?requires=system@3.1.0-SNAPSHOT,map@3.1.0-SNAPSHOT
Response
[{
    "name": "ct",
    "version": "3.1.0-SNAPSHOT",
    "main": "main",
    "location": "http:\/\/localhost:8080\/js\/ct"
},
{
    "name": "map",
    "version": "3.1.0-SNAPSHOT",
    "main": "main",
    "location": "http:\/\/localhost:8080\/js\/bundles\/mapcore\/map"
},
{
    "name": "system",
    "version": "3.1.0-SNAPSHOT",
    "main": "main",
    "location": "http:\/\/localhost:8080\/js\/bundles\/base\/system"
},
...
]
Query Parameter
Name Default Description

requires

List of required package names.

The syntax is <name>@<version range expression>

<name> must be a well-known package name, for example map

<version range expression> this part (including the @ sign) is optional

A version range expression can be a concrete version or a range like defined in the dependencies section of a package.json.

requires_skip

List of required dependencies to be skipped, same syntax like requires.

transitive

true

If enabled, transitive resolved dependencies are included in the response.

Fetch packages info from root

The registry root can directly be requested for required packages.

Request
GET /resources/jsregistry/root?requires=map@3.1.0-SNAPSHOT&inline=true
Response
{
    "coordinatetransformer": {
        "name": "coordinatetransformer",
        "dist-tags": {
            "latest": "3.1.0-SNAPSHOT"
        },
        "versions": {
            "3.1.0-SNAPSHOT": {
                ...
                "_id": "coordinatetransformer@3.1.0-SNAPSHOT",
                "location": "http:\/\/localhost:8080\/js\/bundles\/mapcore\/coordinatetransformer"
            }
        }
    },
    "geometryservice": {
        "name": "geometryservice",
        "dist-tags": {
            "latest": "3.1.0-SNAPSHOT"
        },
        "versions": {
            "3.1.0-SNAPSHOT": {
                ...
                "_id": "geometryservice@3.1.0-SNAPSHOT",
                "location": "http:\/\/localhost:8080\/js\/bundles\/mapcore\/geometryservice"
            }
        }
    },
    "map": {
        "name": "map",
        "dist-tags": {
            "latest": "3.1.0-SNAPSHOT"
        },
        "versions": {
            "3.1.0-SNAPSHOT": {
                ...
                "_id": "map@3.1.0-SNAPSHOT",
                "location": "http:\/\/localhost:8080\/js\/bundles\/mapcore\/map"
            }
        }
    }
}
Query Parameter
Name Default Description

requires

List of required package names.

The syntax is <name>@<version range expression>

<name> must be a well-known package name, for example map

<version range expression> this part (including the @ sign) is optional

A version range expression can be a concrete version or a range like defined in the dependencies section of a package.json.

requires_skip

List of required dependencies to be skipped, same syntax like requires.

transitive

true

If enabled, transitive resolved dependencies are included in the response.

inline

false

If false, the listed versions containing a link to the package info otherwise the package info is embedded.

Fetch packages info from bundles.json

This endpoint is semantically equal to fetching the packages info directly from the root. However, it provides some additional query parameters to preserve compatibility with map.apps releases earlier than 3.1.0.

Request
GET /resources/jsregistry/root/bundles.json?needed=map@3.1.0-SNAPSHOT
Response
{
    "coordinatetransformer": {
        "name": "coordinatetransformer",
        "dist-tags": {
            "latest": "3.1.0-SNAPSHOT"
        },
        "versions": {
            "3.1.0-SNAPSHOT": {
                ...
                "_id": "coordinatetransformer@3.1.0-SNAPSHOT",
                "location": "http:\/\/localhost:8080\/js\/bundles\/mapcore\/coordinatetransformer"
            }
        }
    },
    "geometryservice": {
        "name": "geometryservice",
        "dist-tags": {
            "latest": "3.1.0-SNAPSHOT"
        },
        "versions": {
            "3.1.0-SNAPSHOT": {
                ...
                "_id": "geometryservice@3.1.0-SNAPSHOT",
                "location": "http:\/\/localhost:8080\/js\/bundles\/mapcore\/geometryservice"
            }
        }
    },
    "map": {
        "name": "map",
        "dist-tags": {
            "latest": "3.1.0-SNAPSHOT"
        },
        "versions": {
            "3.1.0-SNAPSHOT": {
                ...
                "_id": "map@3.1.0-SNAPSHOT",
                "location": "http:\/\/localhost:8080\/js\/bundles\/mapcore\/map"
            }
        }
    }
}
Query Parameter
Name Default Description

needed

*

List of required package names.

The syntax is <name>@<version range expression>

<name> must be a well-known package name, for example map

<version range expression> this part (including the @ sign) is optional

A version range expression can be a concrete version or a range like defined in the dependencies section of a package.json.

skipped

List of required dependencies to be skipped, same syntax like needed.
The response of a bundles.json endpoint matches the query /resources/jsregistry/root?requires=<needed>&requires_skip=<skipped>&transitive=true&inline=true

JavaScript Layer File Generation

A JavaScript layer file is a file containing a number of other JavaScript files. This helps to minimize HTTP requests required to fetch the files requested by an application. A layer file has the following AMD loader compatible format:

require({
    cache:{
        "<module identifier>":function(){
            //filebody
        },
        ...
    }
});

<module identifier> is the ID of the file used by the amd loader, for example system/module or dojo/async.

<file body> is the content of the original JavaScript file.

This format ensures that the body of an embedded JavaScript file is only evaluated if required by the AMD loader.

The registry allows to dynamically generate JavaScript layer files. A prerequisite is an existing dependencies.json file provided by the installed packages. This file describes the dependencies between files located in this very package and files located in other packages. A dependencies.json file can be generated with the jsregistry-maven-plugin.

Fetch layer file from layer.js

This is the recommended endpoint to generate layer files.

This is an HTTP version of the buildLayers goal of the jsregistry-maven-plugin. This means that the special syntax defined for includes and excludes is working with this endpoint.
Request
GET /resources/jsregistry/root/layer.js?requires=system@3.1.0-SNAPSHOT/module&requires_skip=dojo/*,ct/*
Response
require({
    cache: {
        "system/module": function(){ ... },
        ...
    }
});
Query Parameter
Name Default Description

requires

List of required dependencies.

The syntax is <package declaration>/<file>

The syntax of a <package declaration> is <mid>@<version range expression>

<mid> must be a well known package name, for example map

<version range expression> this part (including the @ sign) is optional

A version range expression can be a concrete version or a range like defined in the dependencies section of a package.json.

<file> is a identifier of a JavaScript file inside the package, for example main or module.

The <file> part including the / is optional. If not specified the file defined by the layer property of the package.json is delivered.

Special Syntax Elements:

^<package declaration>/<file>: defines that the file is included before the require expression

+<package declaration>/<file>: defines that the file is included after the require expression

requires_skip

List of dependencies to be skipped. This is the same syntax like requires but with own special syntax elements.

Special Syntax Elements:

!<package declaration>/<file>: exclude the file, but integrate all dependencies.

+<package declaration>/<file>: include the file, but exclude all dependencies.

<package declaration>/*: all files from the specific package and also their dependencies.

!<package declaration>/*: exclude only the files which from the specific package, but include their dependencies.

transitive

true

Flag if the package resolution is transitive. If false only files from packages directly resolved from the requires and requires_skip parameters are included into the layer file.

locale

A comma separated list of locales, for example de,en. This allows to include language files into the JavaScript layer. By default the root i18n file, which is usually English, is included.

lang

Same as locale (only recognized if locale is not used)

printIncluded

false

This switches the output of the request to a list of included filenames. This is useful to check the correct behavior.

Sample of a response with printIncluded=true:

Request
GET /resources/jsregistry/root/layer.js?requires=system@3.1.0-SNAPSHOT/main&requires_skip=dojo/*,ct/*&locale=de&printIncluded=true
Response
define([
    "system/main",
    "system/nls/bundle",
    "system/nls/de/bundle"
]);

Fetch layer file from bundles.js

This endpoint is provided to preserver compatibility to the current map.apps Launcher. It has the same functionality as the layer.js endpoint but some parameters have different names.

Request
GET /resources/jsregistry/root/bundles.js?mids=system@3.1.0-SNAPSHOT/module&skip=dojo/*,ct/*
Response
require({
    cache: {
        "system/module": function(){ ... },
        ...
    }
});
Query Parameter
Name Default Description

mids

Exactly defined like the requires parameter of the layer.js endpoint.

skip

Exactly defined like the requires_skip parameter of the layer.js endpoint.

transitive

true

See the layer.js endpoint.

locale

See the layer.js endpoint.

lang

See the layer.js endpoint.

printIncluded

false

See the layer.js endpoint.