diff --git a/sidebars/subhosting.js b/sidebars/subhosting.js index 3fe408098..62f3b3e22 100644 --- a/sidebars/subhosting.js +++ b/sidebars/subhosting.js @@ -22,6 +22,11 @@ const sidebars = { label: "Planning your implementation", id: "manual/planning_your_implementation", }, + { + type: "doc", + label: "Pricing and Limits", + id: "manual/pricing_and_limits", + }, { type: "html", value: "
REST API
", @@ -30,10 +35,14 @@ const sidebars = { { type: "doc", label: "Resources", - id: "manual/subhosting", + id: "api/index", + }, + { + type: "doc", + label: "Authentication", + id: "api/authentication", }, "manual/events", - "api/index", { type: "link", label: "API Reference Docs", diff --git a/subhosting/api/index.md b/subhosting/api/index.md index 9e4a32e61..7bdb1af60 100644 --- a/subhosting/api/index.md +++ b/subhosting/api/index.md @@ -1,44 +1,140 @@ -# Authentication +# Subhosting Resources -Developers can provision projects, domains, KV databases, and other resources -using the Subhosting REST API. +To build Subhosting with Deno Deploy, it helps to understand some key resources +within the system. These resources are also represented in the +[REST API](../api/index.md). -## Endpoint and authentication +![overview of subhosting resources](./images/subhosting-org-structure.svg) -The base URL for the Subhosting REST API v1 is below. + + +## Organizations + +[**Organizations**](https://apidocs.deno.com/#get-/organizations/-organizationId-) +are a container for all data related to a subhosting implementation. Your +organization will have a name and an ID. Each organization has an analytics +endpoint which can be used to get metrics (such as request count and bandwidth +used) from across the organization. + +Other Deploy users can be invited to collaborate on an organization, and +[access tokens](https://dash.deno.com/account#access-tokens) can give developers +with organization access the ability to modify resources within the org via API. +New organizations can be created in the +[Deploy dashboard](https://dash.deno.com/orgs/new). + + + +## Projects + +[**Projects**](https://apidocs.deno.com/#get-/organizations/-organizationId-/projects) +act as organizational containers for deployments. A project contains its +deployments and the analytics and usage information for those deployments. + +Projects are free and can be set up as required. + +To track usage by individual users for billing there is an API endpoint that +reports analytics (bandwidth usage, request count, etc), per project, with 15 +minute granularity. + +> All deployments (whether within a same project or between different projects) +> share nothing by default. Projects are a way to organize your deployments and +> do not cost anything. However analytics are reported on a per-project basis, +> if you have multiple tenants we recommend setting up a project for each. +> Particularly if you expect to bill your users for their usage. + + + +## Deployments + +[**Deployments**](https://apidocs.deno.com/#get-/projects/-projectId-/deployments): +a deployment is a set of configuration, runnable code, and supporting static +files that can run on an isolate in Deno Deploy. Deployments have an entry file +that can launch a server, can have a [Deno KV](/deploy/kv/manual) database +associated with them, and can be set up to run on custom domains. + +A deployment is an immutable object that consists of: + +- Source code to run +- Static assets +- Environment variables +- Database bindings +- Other settings + +We provide endpoints for querying or streaming build logs and querying or +streaming execution logs. + +If you need to block or unblock a deployment you can do so by deleting the +deployment that you need to block or by unassigning its domains. This will make +the deployment unreachable. + +The Subhosting system is built so that the behavior or load on one deployment +does not affect other deployments. This also applies to different deployments +within one organization. Capacity is auto-scaled on demand. If you want to limit +resources to a particular deployment or application you can use the analytics +API to provide you with detailed metrics (request count, bandwidth, etc) at +project level granularity. You can use this to decide whether to shut off +deployments and make them unreachable. + +> NB. **Deployments are immutable**, however, you can create a new deployment +> and then remap its domain to the new deployment. The redeploy endpoint can +> create a new deployment from an existing one with different settings. + + + +## Custom domains + +[** Custom domains**](https://apidocs.deno.com/#get-/organizations/-organizationId-/domains) +can be dynamically mapped to deployments, giving them a unique URL (eg +`mycompany.com`). + +Before a domain can be used you need to +[verify ownership and provision +or upload TLS certificates](https://github.com/denoland/deploy-api/blob/main/samples.ipynb). + +If you are on the [Builder tier](https://deno.com/deploy/pricing?subhosting) you +can use wildcard domains. Once you have a wildcard domain registered, you can +use it in two ways: + +- Send all requests for `*.mycompany.com` to a specific deployment +- (Coming soon) Assign different subdomains (e.g. `foo.mycompany.com` and + `bar.mycompany.com`) to separate deployments. + +### Staging vs Production Environments + +The Deno Deploy end-user platform automatically creates preview deployments when +a developer opens a github pull request, and commits to the “main” branch are +automatically turned into production deployments. Although subhosting does not +provide github integration out of the box, it has all the primitives you need to +define your own semantics for creating preview and production deployments. + + + +## Connecting a KV Database + +A (KV) database stores key-value pairs You can make a database accessible to a +deployment when you make the deployment. KV databases can be used by multiple +deployments at the same time. + +To use KV with Subhosting: + +- [Create a database using the API](https://docs.deno.com/deploy/kv/manual) +- When you create a deployment using the Subhosting API, specify the database + you created. + +> NB. Deno Cron and Queues do not currently work for Subhosting. + + +## OpenAPI specification and tooling + +The [OpenAPI specification](https://www.openapis.org/) for the Deploy API can be +found here: ```console -https://api.deno.com/v1/ +https://api.deno.com/v1/openapi.json ``` -The v1 API uses -[HTTP bearer token](https://swagger.io/docs/specification/authentication/bearer-authentication/) -authentication. You can create an access token to use the API in the dashboard -[here](https://dash.deno.com/account#access-tokens). Most API requests will also -require your organization ID. You can retrieve yours from the Deno Deploy -dashboard for your organization. - -![Find your org ID here](./images/org-id.png) - -Using both your organization ID and your access token, you can test your API -access by listing all the projects associated with your organization. Here is an -example Deno script you can use to access the API. - -```typescript -// Replace these with your own! -const organizationId = "a75a9caa-b8ac-47b3-a423-3f2077c58731"; -const token = "ddo_u7mo08lBNHm8GMGLhtrEVfcgBsCuSp36dumX"; - -const res = await fetch( - `https://api.deno.com/v1/organizations/${organizationId}/projects`, - { - method: "GET", - headers: { - Authorization: `Bearer ${token}`, - }, - }, -); - -const response = await res.json(); -console.log(response); -``` +This spec document can be used with a +[large number of OpenAPI-compatible tools](https://openapi.tools/). In addition +to the documentation for the REST API maintained here, you can find +auto-generated API documentation (including a browser-based testing tool) +[here](https://apidocs.deno.com/). diff --git a/subhosting/manual/subhosting-org-structure.svg b/subhosting/manual/subhosting-org-structure.svg deleted file mode 100644 index 6fb054e0b..000000000 --- a/subhosting/manual/subhosting-org-structure.svg +++ /dev/null @@ -1,87 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/subhosting/manual/subhosting.md b/subhosting/manual/subhosting.md deleted file mode 100644 index 30b251f7b..000000000 --- a/subhosting/manual/subhosting.md +++ /dev/null @@ -1,140 +0,0 @@ -# Subhosting Resources - -To build Subhosting with Deno Deploy, it helps to understand some key resources -within the system. These resources are also represented in the -[REST API](../api/index.md). - -![overview of subhosting resources](./subhosting-org-structure.svg) - - - -## Organizations - -[**Organizations**](https://apidocs.deno.com/#get-/organizations/-organizationId-) -are a container for all data related to a subhosting implementation. Your -organization will have a name and an ID. Each organization has an analytics -endpoint which can be used to get metrics (such as request count and bandwidth -used) from across the organization. - -Other Deploy users can be invited to collaborate on an organization, and -[access tokens](https://dash.deno.com/account#access-tokens) can give developers -with organization access the ability to modify resources within the org via API. -New organizations can be created in the -[Deploy dashboard](https://dash.deno.com/orgs/new). - - - -## Projects - -[**Projects**](https://apidocs.deno.com/#get-/organizations/-organizationId-/projects) -act as organizational containers for deployments. A project contains its -deployments and the analytics and usage information for those deployments. - -Projects are free and can be set up as required. - -To track usage by individual users for billing there is an API endpoint that -reports analytics (bandwidth usage, request count, etc), per project, with 15 -minute granularity. - -> All deployments (whether within a same project or between different projects) -> share nothing by default. Projects are a way to organize your deployments and -> do not cost anything. However analytics are reported on a per-project basis, -> if you have multiple tenants we recommend setting up a project for each. -> Particularly if you expect to bill your users for their usage. - - - -## Deployments - -[**Deployments**](https://apidocs.deno.com/#get-/projects/-projectId-/deployments): -a deployment is a set of configuration, runnable code, and supporting static -files that can run on an isolate in Deno Deploy. Deployments have an entry file -that can launch a server, can have a [Deno KV](/deploy/kv/manual) database -associated with them, and can be set up to run on custom domains. - -A deployment is an immutable object that consists of: - -- Source code to run -- Static assets -- Environment variables -- Database bindings -- Other settings - -We provide endpoints for querying or streaming build logs and querying or -streaming execution logs. - -If you need to block or unblock a deployment you can do so by deleting the -deployment that you need to block or by unassigning its domains. This will make -the deployment unreachable. - -The Subhosting system is built so that the behavior or load on one deployment -does not affect other deployments. This also applies to different deployments -within one organization. Capacity is auto-scaled on demand. If you want to limit -resources to a particular deployment or application you can use the analytics -API to provide you with detailed metrics (request count, bandwidth, etc) at -project level granularity. You can use this to decide whether to shut off -deployments and make them unreachable. - -> NB. **Deployments are immutable**, however, you can create a new deployment -> and then remap its domain to the new deployment. The redeploy endpoint can -> create a new deployment from an existing one with different settings. - - - -## Custom domains - -[** Custom domains**](https://apidocs.deno.com/#get-/organizations/-organizationId-/domains) -can be dynamically mapped to deployments, giving them a unique URL (eg -`mycompany.com`). - -Before a domain can be used you need to -[verify ownership and provision -or upload TLS certificates](https://github.com/denoland/deploy-api/blob/main/samples.ipynb). - -If you are on the [Builder tier](https://deno.com/deploy/pricing?subhosting) you -can use wildcard domains. Once you have a wildcard domain registered, you can -use it in two ways: - -- Send all requests for `*.mycompany.com` to a specific deployment -- (Coming soon) Assign different subdomains (e.g. `foo.mycompany.com` and - `bar.mycompany.com`) to separate deployments. - -### Staging vs Production Environments - -The Deno Deploy end-user platform automatically creates preview deployments when -a developer opens a github pull request, and commits to the “main” branch are -automatically turned into production deployments. Although subhosting does not -provide github integration out of the box, it has all the primitives you need to -define your own semantics for creating preview and production deployments. - - - -## Connecting a KV Database - -A (KV) database stores key-value pairs You can make a database accessible to a -deployment when you make the deployment. KV databases can be used by multiple -deployments at the same time. - -To use KV with Subhosting: - -- [Create a database using the API](https://docs.deno.com/deploy/kv/manual) -- When you create a deployment using the Subhosting API, specify the database - you created. - -> NB. Deno Cron and Queues do not currently work for Subhosting. - - -## OpenAPI specification and tooling - -The [OpenAPI specification](https://www.openapis.org/) for the Deploy API can be -found here: - -```console -https://api.deno.com/v1/openapi.json -``` - -This spec document can be used with a -[large number of OpenAPI-compatible tools](https://openapi.tools/). In addition -to the documentation for the REST API maintained here, you can find -auto-generated API documentation (including a browser-based testing tool) -[here](https://apidocs.deno.com/). diff --git a/subhosting/manual/usecases.md b/subhosting/manual/usecases.md deleted file mode 100644 index d67d7f65e..000000000 --- a/subhosting/manual/usecases.md +++ /dev/null @@ -1,20 +0,0 @@ -# Subhosting Usecases - -- Reselling serverless edge functions - - _Netlify_ runs edge functions written by their customers -- Customer written API adapters - - ? -- Simple customizations in low-code solutions - - E.g. ferrio -- Edge front-ends for websites/CMSs/ecommerce - - Deco.cx case study -- Customer developed widgets - - E.g. retune -- Executable code snippets (e.g. in documentation) - - Redocly (if they are still using subhosting) -- Scope of this documentation -- This doc covers how a SaaS application can programmatically deploy their end - user code to our platform. -- Documentation for end users is here -> link -How do I integrate an open source editor? -See our blog post about monaco