HTTP API

This document describes the different HTTP APIs available on a running Eik server.

Authentication

Authentication is needed to execute multiple API calls in the REST API.

Endpoint Summary Table

Name	Verb	Endpoint	Form Fields
Login	POST	/auth/login	key

Login

Method: POST

Logs a user in to the service.

https://:assetServerUrl:port/auth/login

Form parameters:

• key an authentication key

Status codes:

• 200 if user is authorized
• 401 if user is not authorized

Success response: A jwt token

{
	"token": "..."
}

Example:

curl -X POST -i -F key=rfm940c3 http://localhost:4001/auth/login

Packages

A packages is a set of files (javascript, css etc) that is intended to be referenced from an HTML document and loaded by a browser.

Packages are versioned and consist of one or more files. A package of a specific version is immutable.

Endpoint Summary Table

Name	Verb	Endpoint	Form Fields
Public Package URL	GET	/pkg/:name/:version/:extras
Upload a Package	PUT	/pkg/:name/:version	package

Public Package URL

Method: GET

Retrieves files from a package on the service.

https://:assetServerUrl:port/pkg/:name/:version/:extras

URL parameters:

• :name is the name of the package. Validator: Comply with npm package names.
• :version is the version of the package. Validator: Comply with semver validation regex.
• :extras whildcard pathname to any file in the package

Status codes:

• 200 if file is successfully retrieved
• 404 if file is not found

Example:

curl -X GET http://localhost:4001/pkg/fuzz/8.4.1/main/index.js

Upload a package

Method: PUT

Puts a new package at the service.

https://:assetServerUrl:port/pkg/:name/:version

URL parameters:

• :name is the name of the package. Validator: Comply with npm package names.
• :version is the version of the package. Validator: Comply with semver validation regex.

Form parameters:

• package a tar or tar.gz containing the files of the package

HTTP headers:

• Authorization a jwt authorization bearer with the token retrieved from a successful authentication

Status codes:

• 303 if package is successfully uploaded. location is root of module
• 400 if validation in URL parameters or form fields fails
• 401 if user is not authorized
• 409 if package already exists or version in a major range is not newer than previous version in a major range
• 413 if package is too large
• 415 if file format of the uploaded file is unsupported
• 422 if a entry in the uploaded file could not be parsed or errored
• 502 if package could not be written to the sink

Example:

curl -X PUT -i -F package=@archive.tgz -H "Authorization: Bearer {:token}" http://localhost:4001/pkg/fuzz/8.4.1

Latest Package versions

Method: GET

Retrieves an overview of the latest major versions of a package.

https://:assetServerUrl:port/pkg/:name

URL parameters:

• :name is the name of the package. Validator: Comply with npm package names.

Status codes:

• 200 if file is successfully retrieved
• 404 if file is not found

Example:

curl -X GET http://localhost:4001/pkg/fuzz

Package version overview

Method: GET

Retrieves an overview of the files of a package version.

https://:assetServerUrl:port/pkg/:name/:version

URL parameters:

• :name is the name of the package. Validator: Comply with npm package names.
• :version is the version of the package. Validator: Comply with semver validation regex.

Status codes:

• 200 if file is successfully retrieved
• 404 if file is not found

Example:

curl -X GET http://localhost:4001/pkg/fuzz

NPM Packages

An NPM package is a local replica of a package found in the NPM registry intended to be referenced from an HTML document and loaded by a browser. In most cases, with some exceptions, an NPM Package will be a library or utillity that other Packages depend upon.

NPM Packages are versioned and consist of one or more files. An NPM package of a specific version is immutable.

Endpoint Summary Table

Name	Verb	Endpoint	Form Fields
Public NPM Package URL	GET	/npm/:name/:version/:extras
Upload an NPM Package	PUT	/npm/:name/:version	package

Public NPM Package URL

Method: GET

Retrieves files from an NPM package on the service.

https://:assetServerUrl:port/npm/:name/:version/:extras

URL parameters:

• :name is the name of the NPM package. Validator: Comply with npm package names.
• :version is the version of the NPM package. Validator: Comply with semver validation regex.
• :extras wildcard pathname to any file in the NPM package

Status codes:

• 200 if file is successfully retrieved
• 404 if file is not found

Example:

curl -X GET http://localhost:4001/npm/fuzz/8.4.1/main/index.js

Upload a NPM Package

Method: PUT

Puts a new NPM package on the service.

https://:assetServerUrl:port/npm/:name/:version

URL parameters:

• :name is the name of the NPM package. Validator: Comply with npm package names.
• :version is the version of the NPM package. Validator: Comply with semver validation regex.

Form parameters:

• package a tar or tar.gz containing the files of the NPM package

HTTP headers:

• Authorization a JWT authorization bearer with the token retrieved from a successful authentication

Status codes:

• 303 if NPM package is successfully uploaded. location is root of module
• 400 if validation in URL parameters or form fields fails
• 401 if user is not authorized
• 409 if NPM package already exist or version in a major range is not newer than previous version in a major range
• 413 if package is too large
• 415 if file format of the uploaded file is unsupported
• 422 if a entry in the uploaded file could not be parsed or errored
• 502 if NPM package could not be written to the sink

Example:

curl -X PUT -i -F package=@archive.tgz -H "Authorization: Bearer {:token}" http://localhost:4001/npm/fuzz/8.4.1

Latest NPM Package versions

Method: GET

Retrieves an overview of the latest major versions of an NPM package.

https://:assetServerUrl:port/npm/:name

URL parameters:

• :name is the name of the NPM package. Validator: Comply with npm package names.

Status codes:

• 200 if file is successfully retrieved
• 404 if file is not found

Example:

curl -X GET http://localhost:4001/npm/fuzz

NPM Package version overview

Method: GET

Retrieves an overview of the files of an NPM package version.

https://:assetServerUrl:port/npm/:name/:version

URL parameters:

• :name is the name of the NPM package. Validator: Comply with npm package names.
• :version is the version of the NPM package. Validator: Comply with semver validation regex.

Status codes:

• 200 if file is successfully retrieved
• 404 if file is not found

Example:

curl -X GET http://localhost:4001/npm/fuzz

Import Maps

An import map holds a mapping or a set of mappings between ECMA Script Module (ESM) bare imports and an absolute URL. Import maps are versioned and are immutable.

Endpoint Summary Table

Name	Verb	Endpoint	Form Fields
Public Import Map URL	GET	/map/:name/:version
Upload an Import Map	PUT	/map/:name/:version	map

Public Import Map URL

Method: GET

Retrieves an import map from the service.

https://:assetServerUrl:port/map/:name/:version

URL parameters:

• :name is the name of the import map. Validator: Comply with npm package names.
• :version is the version of the import map. Validator: Comply with semver validation regex.

Status codes:

• 200 if import map is successfully retrieved
• 404 if import map is not found

Example:

curl -X GET http://localhost:4001/map/buzz/8.4.1

Upload an Import Map

Method: PUT

Puts a new import map at the service.

https://:assetServerUrl:port/map/:name/:version

URL parameters:

• :name is the name of the import map. Validator: Comply with npm package names.
• :version is the version of the import map. Validator: Comply with semver validation regex.

Form parameters:

• map a json file (the import map)

HTTP headers:

• Authorization a jwt authorization bearer with the token retrieved from a successful authentication

Status codes:

• 303 if import map is successfully uploaded. location is Public Import Map URL
• 400 if validation in URL parameters or form fields fails
• 401 if user is not authorized
• 409 if import map already exist
• 415 if file format of the uploaded import map is unsupported
• 502 if import map could not be written to the sink

Example:

curl -X PUT -i -F map=@import-map.json -H "Authorization: Bearer {:token}" http://localhost:4001/map/buzz/8.4.1

Latest Import Map versions

Method: GET

Retrieves an overview of the latest versions of a Import Map.

https://:assetServerUrl:port/map/:name

URL parameters:

• :name is the name of the import map. Validator: Comply with npm package names.

Status codes:

• 200 if file is successfully retrieved
• 404 if file is not found

Example:

curl -X GET http://localhost:4001/map/buzz

Aliases

An alias is a shorthand between a major version of a package / import map and the set exact version of the package / import map.

Endpoint Summary Table

Name	Verb	Endpoint	Form Fields
Public Alias URL	GET	/:type/:name/v:alias/:extras
Create Alias	PUT	/:type/:name/v:alias	version
Update Alias	POST	/:type/:name/v:alias	version
Delete Alias	DELETE	/:type/:name/v:alias

Public Alias URL

Method: GET

Retrieves files from a package or an import map at the service.

https://:assetServerUrl:port/:type/:name/v:alias/:extras

URL parameters:

• :type is the type to retrieve from. Validator: pkg, npm or map.
• :name is the name of the package / import map. Validator: Comply with npm package names.
• :alias is the major version of the package / import map. Validator: Comply with semver validation regex.
• :extras whildcard pathname to any file in a package. Does not apply to import maps.

Status codes:

• 302 if alias exist
• 404 if alias is not found

Example:

curl -X GET -L http://localhost:4001/pkg/fuzz/v8/main/index.js
curl -X GET -L http://localhost:4001/map/buzz/v4

Create Alias

Method: PUT

Create a new alias.

https://:assetServerUrl:port/:type/:name/v:alias

URL parameters:

• :type is the type to retrieve from. Validator: pkg, npm or map.
• :name is the name of the package / import map. Validator: Comply with npm package names.
• :alias is the major version of the package / import map. Validator: Comply with semver validation regex.

Form parameters:

• :version full version of the package to be aliased

HTTP headers:

• Authorization a jwt authorization bearer with the token retrieved from a successful authentication

Status codes:

• 303 if alias is successfully created. location points to the alias
• 400 if validation in URL parameters or form fields fails
• 401 if user is not authorized
• 409 if alias already exist
• 502 if alias could not be altered by the sink

Example:

curl -X PUT -i -F version=8.4.1 -H "Authorization: Bearer {:token}" http://localhost:4001/pkg/fuzz/v8
curl -X PUT -i -F version=4.2.2 -H "Authorization: Bearer {:token}" http://localhost:4001/map/buzz/v4

Update Alias

Method: POST

Updates an existing alias.

https://:assetServerUrl:port/:type/:name/v:alias

URL parameters:

• :type is the type to retrieve from. Validator: pkg, npm or map.
• :name is the name of the package / import map. Validator: Comply with npm package names.
• :alias is the major version of the package / import map. Validator: Comply with semver validation regex.

Form parameters:

• :version full version of the package to be aliased

HTTP headers:

• Authorization a jwt authorization bearer with the token retrieved from a successful authentication

Status codes:

• 303 if alias is successfully created. location points to the alias
• 401 if user is not authorized
• 404 if alias does not exist
• 502 if alias could not be altered by the sink

Example:

curl -X POST -i -F version=8.4.1 -H "Authorization: Bearer {:token}" http://localhost:4001/pkg/fuzz/v8
curl -X POST -i -F version=4.4.2 -H "Authorization: Bearer {:token}" http://localhost:4001/map/buzz/v4

Delete Alias

Method: DELETE

Deletes an existing alias.

https://:assetServerUrl:port/:type/:name/v:alias

URL parameters:

• :type is the type to retrieve from. Validator: pkg, npm or map.
• :name is the name of the package / import map. Validator: Comply with npm package names.
• :alias is the major version of the package / import map. Validator: Comply with semver validation regex.

HTTP headers:

• Authorization a jwt authorization bearer with the token retrieved from a successful authentication

Status codes:

• 204 if alias is successfully deleted
• 401 if user is not authorized
• 404 if alias does not exist
• 502 if alias could not be altered by the sink

Example:

curl -X DELETE -H "Authorization: Bearer {:token}" http://localhost:4001/pkg/fuzz/v8
curl -X DELETE -H "Authorization: Bearer {:token}" http://localhost:4001/map/buzz/v4