Applications and targets

Create and change applications, choose their visibility, loader mode and source map policy, define their frontend and backend targets, and bind an application to a Beyond project.

  • Availability: Planned
  • Evidence: Read from source
  • Reference

Operations

Operation Request Capability Retry
applications.list GET /v1/organizations/{organization}/applications application.read
applications.create POST /v1/organizations/{organization}/applications application.manage key
applications.read GET /v1/applications/{application} application.read
applications.change PATCH /v1/applications/{application} application.manage version
applications.remove DELETE /v1/applications/{application} application.manage natural
targets.list GET /v1/applications/{application}/targets application.read
targets.define PUT /v1/applications/{application}/targets/{target} application.manage natural
targets.remove DELETE /v1/applications/{application}/targets/{target} application.manage natural
projects.read GET /v1/projects/{project} application.read
projects.bind PUT /v1/applications/{application}/project application.manage natural
projects.release DELETE /v1/applications/{application}/project application.manage natural

The retry kinds are explained in Authentication and conventions.

applications.list takes the optional query parameter project, a project identity: it answers only the applications bound to that project, pending links included. The three projects.* operations are explained under The project of an application.

The application

Member Values Default Notes
name ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ Required Unique inside the organization, and the default label of the testing subdomain. A taken name is 409 NAME_CONFLICT.
title Up to 120 characters Display name
visibility public, private public private requires the private_apps entitlement and the access.manage capability in addition to application.manage. Without the entitlement: 403 ENTITLEMENT_REQUIRED.
loader esm, system esm The loader mode of its web releases
sourcemaps restricted, public, none restricted See source maps
notices true, false true Whether dependency update notices are produced. A notice never upgrades or activates anything.
project A project identity, ^prj_[0-9a-f]{24}$ Only in applications.create: registers the application for that Beyond project in the same request. In an application document, project is the link described below, and it is absent when the application belongs to no project.
version Integer Increases with every change. Send it as expected_version when you change the application.
JSON
{
  "name": "shop",
  "title": "Shop",
  "visibility": "public",
  "loader": "esm",
  "sourcemaps": "restricted"
}

Changing an application

PATCH takes the members to change and expected_version. Changes apply to releases prepared afterwards: an existing release is immutable and keeps the loader, source map policy and visibility it was prepared with.

Making an application private takes effect on delivery within the configured revocation bound.

Deleting an application

Deleting unbinds its environments and domains and revokes its guest grants. Its sources and artifacts are released to garbage collection, which keeps whatever other releases and in-flight jobs still reference. An application in a state that does not allow deletion answers 409 STATE_INVALID.

The project of an application

A Beyond project is one identity that Workspace, Delegate and CDN share. In the CDN it is a reference on an application and nothing more.

  • An application belongs to at most one project. A project may have many applications. An application with no project stays valid: nothing requires a project to register, prepare, release, bind a domain or serve.
  • The project must belong to the organization of the application.
  • Binding and releasing change no application, release, target or output identifier, no URL, no quota, plan or credit. Published delivery never reads the reference and serves the same whether or not Projects answers.
  • Applications and projects are related by identifier only, never by name.

An application that belongs to a project carries project:

Member Values Meaning
id ^prj_[0-9a-f]{24}$ The project identity
state pending, bound bound: Projects confirmed the link. pending: the CDN recorded the reference and Projects has not confirmed it yet. The application exists and works either way
bound Time When the reference was recorded
by Opaque The member who recorded it

projects.read answers the project as Projects reports it at that moment; the CDN keeps no copy:

Member Values Meaning
id ^prj_[0-9a-f]{24}$ The project identity
organization Opaque The organization that owns it
name Up to 200 characters Its name in Projects
state active, archived, deleted Its state in Projects
url URI, optional The address of the project in Beyond Projects, from the configuration of the installation. Absent when none is configured

A project of an organization you do not belong to answers the same 404 NOT_FOUND as one that does not exist.

Bind, register for a project, and release

projects.bind takes { "project": "prj_…" }.

Answer Meaning
422 PROJECT_UNKNOWN The project does not exist or belongs to another organization. The two are never told apart
409 PROJECT_INACTIVE The project is archived or deleted; details.state carries its state. An archived project takes no new application, and the applications it already has are untouched
409 PROJECT_CONFLICT The application is already bound to another project, here or at Projects; details.current names it. Release it first: there is no implicit move
502 UPSTREAM_UNAVAILABLE Projects did not answer. It is neither a refusal nor an approval. The reference stays pending, and repeating the request converges
501 NOT_IMPLEMENTED This service instance is not connected to Projects
409 STATE_INVALID A release of the link ran while Projects was being asked. The release wins and the application stays unbound

Repeating a bind for the same project leaves the same state and confirms a pending link.

applications.create with project checks the project before anything is created, so PROJECT_UNKNOWN, PROJECT_INACTIVE, UPSTREAM_UNAVAILABLE and NOT_IMPLEMENTED create nothing. The answer is the application as it stands: project.state is bound when Projects confirmed and pending when it did not, never bound for a link nobody confirmed. A retry with the same Idempotency-Key creates no second application and asks Projects again while the link is pending.

projects.release removes the reference only, at Projects first and then here. The application, its targets, releases, environment bindings, domains, grants and published outputs stay exactly as they are, and it can be bound again. Releasing an application that belongs to no project answers the same. When Projects does not answer, nothing changes and the answer is 502 UPSTREAM_UNAVAILABLE.

Binding and releasing are announced by the existing event application.changed, with data.change equal to project.bound or project.released. There is no new event type.

Archiving or deleting a project in Beyond Projects destroys nothing in the CDN. It only stops new applications from being bound to it.

Targets

A target is one entry of the application. The path parameter is its name, ^[a-z][a-z0-9-]{0,31}$, for example web or api.

Member Required Rule
kind Yes frontend or backend
package Yes The package name, optionally prefixed by its provider: npm: when absent
selection Yes An exact version or a range. A range is resolved once per registration and pinned in the graph.
entry Yes A public entry subpath of the package, . for the main export. It is never a path to an internal source file.
conditions No Extra condition names, lowercase
runtime No Backend targets only: a requirement stated to the external consumer, up to 80 characters. The CDN never starts or manages a host.
JSON
{ "kind": "frontend", "package": "@example/app", "selection": "^1.0.0", "entry": "." }

A target takes effect in the next registration. Defining a target prepares nothing by itself. An input this version cannot process, such as an unknown provider, is 422 UNSUPPORTED_INPUT.

Backend targets are delivered as compiled outputs with a frozen resolution. See Backend targets.