This package has been deprecated

Author message:

This package has moved to @commonshost/core See: https://www.npmjs.com/package/@commonshost/core

@http2/api 🏵

Management service for @http2/server and @http2/live.

This acts as coordinator of CDN edge nodes.

The core API:

• receives deployments and other input from clients via its API endpoints,
• uploads files to the object store (S3 or DigitalOcean SPaces),
• stores data in MongoDB (Atlas or self-hosted),
• issues certificates using the ACME protocol (LetsEncrypt),
• publishes notifications to the data stream network (PubNub),
• checks authorisation tokens (Auth0).

Usage

http2api <configuration>

Where <configuration> is the path to a file containing the configuration options. It can be JavaScript or JSON.

Example configuration file: api.conf.example.js

System Dependencies

• acme.sh

Service Dependencies

• LetsEncrypt or ACME API-compatible Certificate Authority
• Auth0
• MongoDB Atlas or any MongoDB instance
• DigitalOcean Spaces or AWS S3 API-compatible object store
• PubNub

Environment Variables and Configuration Options

See: ./api.conf.example.js

Setting up AWS S3 IAM

See: ./setup-aws-iam.md

Authentication

Supply a JSON Web Token (JWT) to authenticate the request. The token is issued by Auth0 and signed using the RS256 algorithm.

Authorization: Bearer eyJhbGciOiJSUzI1NiI...

Content Type

Requests must include a valid content type header. Typically indicating JSON or a multipart request.

curl https://api.http2.live:8888/v1/sites \
  -H "content-type: application/json" \
  ; echo

Errors

A response with HTTP status code 4xx-5xx contains JSON with the following properties.

• message A human readable description of the problem.
• statusCode The HTTP status code.
• error The HTTP status message.

Example:

{
  "message": "Missing uploaded files",
  "error": "Internal Server Error",
  "statusCode": 500
}

IDN

Any use of domain names, in URL path segments or other instances, supports the use of internationalised domain names (IDN). Values are automatically converted to lowercase and normalised to Punycode using the ToASCII algorithm. For example 💩.EXAMPLE.NET becomes xn--ls8h.example.net.

Endpoints

GET /v2/configurations

Scope: global_read

Retrieve stored configurations for all sites.

Supports the if-modified-since header to return a 304 status code if no configurations have been changed.

[
  {
    domain: 'example.net',
    modified: '2020-02-20T02:20:02.202',
    configuration: { ... }
  },
  {
    domain: 'example.com',
    modified: '2020-10-10T10:10:10.101',
    configuration: { ... }
  }
]

GET /v2/domains/available{?domain}

Check whether a domain is still available or already taken by a site.

Returns 200 status code if the domain is available, otherwise returns 410 status code. The response body is always empty.

GET /v2/domains/suggestions{?project}

Retrieve a list of suggested and available domains. Up to 5 strings are returned.

Domains are based on the given project name or randomly generated.

[
  'project.example.net',
  'finest-witty-turtle.example.net',
  'magnificent-kind-sloth.example.net'
]

GET /sites{/domain}/certificate

Not yet implemented.

Retrieve certificate information.

{
  modified: '2020-02-20T02:20:02.202',
  domain: 'example.net',
  san: [
    'example.net',
    '*.example.net',
    'a.example.com',
    'b.example.com'
  ]
}

PUT /sites{/domain}/certificate

Not yet implemented.

Issue a certificate with the given Subject Alternative Name (SAN or subjectAltName) extension field.

{
  san: [
    'example.net',
    '*.example.net',
    'a.example.com',
    'b.example.com'
  ]
}

GET /v2/sites{/domain}/configuration

Scope: global_read or deploy

Retrieve the stored configuration for a domain.

{
  modified: '2020-02-20T02:20:02.202',
  domain: 'example.net',
  configuration: {
    // ... host options ...
  }
}

PATCH /v2/sites{/domain}/configuration

Not yet implemented.

Edit the site configuration.

PUT /v2/sites{/domain}/configuration

Not yet implemented.

Set the site configuration.

GET /v2/sites{/domain}/files{/directory}/

Not yet implemented.

List all files in a given directory.

DELETE /v2/sites{/domain}/files{/file}

Not yet implemented.

Remove a file.

PUT /v2/sites{/domain}/files{/file}

Not yet implemented.

Add or replace a file.

GET /v2/sites{/domain}/info

Not yet implemented.

Get site metadata.

PATCH /v2/sites{/domain}/info

Not yet implemented.

Edit site metadata.

PUT /v2/sites{/domain}/info

Not yet implemented.

Set site metadata.

DELETE /v2/sites{/domain}

Scope: deploy

Unpublish a site. This removes all configuration data and files associated with the site.

Returns 200 upon success, with an empty body.

PUT /v2/sites{/domain}

Scope: deploy

Deploys a site by the given domain. Optionally provide files and a configuration.

If the domain value is invalid, a 400 status is returned. If the site is owned by another user, a 403 status is returned.

Content type of the request must be multipart/form-data.

The configuration field contains JSON data of the host options. A 400 status is returned if the data does not comply with the @http2/configuration host JSON Schema.

There are constraints on the number of individual files as well as the total size of all files.

One or more directory fields contain all files to be deployed. The filename may contain a relative path, as per the webkitdirectory attribute. Any previously hosted files for the domain are removed. To update or remove only a single file, see the /v2/sites{/domain}/files{/file} endpoint.

If a new certificate is required, it will be issued asynchronously.

The response message is also published as a notification.

Returns 200 upon success with an object containing the published domain.

{
  type: 'site-deploy',
  domain: 'example.net',
  isNewDomain: true,
  hasNewFiles: true,
  hasNewConfiguration: true
}

GET /v2/sites

List all sites owned by the authenticated user.

[
  {
    modified: '2020-02-20T02:20:02.202',
    userId: 'auth0|1234567890',
    domain: 'example.net'
  },
  {
    modified: '2020-10-10T10:10:10.101',
    userId: 'auth0|abcdef',
    domain: 'example.com'
  }
]

PATCH /v2/users{/id}

Update the email address or password of the authenticated user.

POST /v1/deploy

Deprecated

Use PUT /v2/sites{/domain} instead.

POST /v1/sites

Deprecated

Use PUT /v2/sites{/domain} instead.

GET /

Retrieve server health information. The uptime value is measured in seconds.

{
  status: 'OK',
  uptime: 120
}

Colophon

Made with ❤️ by Sebastiaan Deckers in 🇸🇬 Singapore.