Skip to main content

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

NameVerbEndpointForm Fields
LoginPOST/auth/loginkey

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

NameVerbEndpointForm Fields
Public Package URLGET/pkg/:name/:version/:extras
Upload a PackagePUT/pkg/:name/:versionpackage

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:

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:

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:

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

NameVerbEndpointForm Fields
Public NPM Package URLGET/npm/:name/:version/:extras
Upload an NPM PackagePUT/npm/:name/:versionpackage

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:

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:

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:

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

NameVerbEndpointForm Fields
Public Import Map URLGET/map/:name/:version
Upload an Import MapPUT/map/:name/:versionmap

Public Import Map URL

Method: GET

Retrieves an import map from the service.

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

URL parameters:

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:

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:

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

NameVerbEndpointForm Fields
Public Alias URLGET/:type/:name/v:alias/:extras
Create AliasPUT/:type/:name/v:aliasversion
Update AliasPOST/:type/:name/v:aliasversion
Delete AliasDELETE/: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