asset-server-v3-api-proposal.md

Asset Server Proposed APIs

Publishing Global dependencies

Publish a global dependency to the server:

POST /:org/:type/:name/:version

Form fields

file

File to upload

data

Metadata to upload with file in JSON format

{
    "filename": "index.js|css",
    "subtype": "default|esm",
    "force": true
}

• data.filename defaults to index.js for JS and index.css for CSS and can generally be omitted.
• data.subtype defaults to esm for JS and default for CSS and can generally be omitted.
• data.force force republish if package has been published before.

Examples

• POST /finn/js/react/16.8.6

Retrieve a global dependency from the server

GET /:org/:type/:name/:version/[:subtype]/[:filename]

• :subtype defaults to esm for JS or default for CSS and can generally be omitted.
• :filename defaults to index.js for JS and index.css for CSS and can generally be omitted.

Examples

• GET /finn/js/react/16.8.6
• GET /finn/js/react/16.8.6/esm
• GET /finn/js/react/16.8.6/esm/index.js
• GET /finn/js/react/16.8.6/esm/index.js.map
• GET /finn/css/react/16.8.6
• GET /finn/css/react/16.8.6/default
• GET /finn/css/react/16.8.6/default/index.css

Managing Aliases

Retrieve a file via its alias (302 redirect)

GET /:org/:type/:name/:alias/[:subtype]/[:filename]

• :subtype defaults to esm for JS or default for CSS and can generally be omitted.
• :filename defaults to index.js for JS and index.css for CSS and can generally be omitted.

Examples

• GET /finn/js/react/v16
• GET /finn/js/react/v16/esm
• GET /finn/js/react/v16/esm/index.js
• GET /finn/js/react/v16/esm/index.js.map
• GET /finn/css/react/v16
• GET /finn/css/react/v16/default
• GET /finn/css/react/v16/default/index.css

Set an alias for a global dependency

PUT /:org/:type/:name/:alias

Form fields

data

Metadata in JSON format

{
    "version": "<semver version> (required)",
    "filename": "index.js|css",
    "subtype": "default|esm"
}

• data.version (required) Semver compliant package version eg. 16.8.6 for the package given by :name in the URL
• data.filename defaults to index.js for JS and index.css for CSS and can generally be omitted.
• data.subtype defaults to esm for JS and default for CSS and can generally be omitted.

Examples

• PUT /finn/js/react/v16

Delete an alias for a global dependency

DELETE /:org/:type/:name/:alias

Examples

• DELETE /finn/js/react/v16

Managing Import Maps

Set a bare import to map to a specific global dependency in an org wide import map file

PUT /:org/:type/import-map/:key

Form fields

data

Metadata in JSON format

{
    "value": "http://url-to-map-to"
}

• data.value (required) URL to map bare import specified by :key in URL to. data.value must be an absolute URL

Examples

• PUT /finn/js/import-map/react data = { "value": "http://asset-server/finn/js/react/v16" }

Delete a bare import mapping from an org wide import map file

DELETE /:org/:type/import-map/:key

Examples:

• DELETE /finn/js/import-map/react

Retrieve an org wide import map file

GET /:org/:type/import-map

Examples

• GET /finn/js/import-map

Publishing Local bundles

Retrieve a local bundle from the asset server

GET /:org/:type/:name/:version/[:subtype]/[:filename]

• :subtype defaults to esm for JS or default for CSS and can generally be omitted.
• :filename defaults to index.js for JS and index.css for CSS and can generally be omitted.

Examples

• GET /finn/js/my-app/1.0.0
• GET /finn/js/my-app/1.0.0/esm
• GET /finn/js/my-app/1.0.0/esm/index.js
• GET /finn/css/my-app/1.0.0
• GET /finn/js/my-app/1.0.0/default
• GET /finn/js/my-app/1.0.0/default/index.css

Publish a local bundle to the asset server

Bundles are immutable, if :version already exists, publish will fail.

POST /:org/:type/:name/:version

Form fields

file

File to upload

data

Metadata to upload with file in JSON format

{
    "filename": "index.js|css",
    "subtype": "default|esm"
}

• data.filename defaults to index.js for JS and index.css for CSS and can generally be omitted.
• data.subtype defaults to esm for JS and default for CSS and can generally be omitted.

Examples

• POST /finn/js/my-app/1.0.0
• POST /finn/js/my-app/1.0.0/esm
• POST /finn/js/my-app/1.0.0/esm/index.js
• POST /finn/css/my-app/1.0.0
• POST /finn/css/my-app/1.0.0/default
• POST /finn/css/my-app/1.0.0/default/index.css