[WIP] Deno Deploy REST API (denoland#172)

dandv · Nov 13, 2023 · c6e62b7 · c6e62b7
1 parent b46c238
commit c6e62b7
Show file tree

Hide file tree

Showing 22 changed files with 2,285 additions and 13 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -5,5 +5,10 @@
   "deno.lint": true,
   "deno.unstable": true,
   "editor.formatOnSave": true,
-  "editor.defaultFormatter": "denoland.vscode-deno"
+  "editor.defaultFormatter": "denoland.vscode-deno",
+  "[markdown]": {
+    "editor.formatOnSave": true,
+    "editor.wordWrap": "on",
+    "editor.defaultFormatter": "denoland.vscode-deno"
+  }
 }
diff --git a/deploy/api/rest/deployments.md b/deploy/api/rest/deployments.md
@@ -0,0 +1,130 @@
+import OpenApiEndpoint from "@site/src/components/OpenApiEndpoint";
+
+# Deployments
+
+A deployment is a container for assets, environment variables, compiler options,
+and other data related to a deployed serverless application.
+
+## Create a deployment
+
+<!-- deno-fmt-ignore-start -->
+
+<OpenApiEndpoint path="/projects/{projectId}/deployments" method="post"
+  customDocs={{ 
+    compilerOptions: "See **Compiler options** below.", 
+    assets: "See **Deployment assets** below.", 
+  }}
+>
+  <p>
+    Initiate a build process for a new deployment. Note that this process is
+    asynchronous - a successful request to this endpoint API doesn't mean the
+    deployment is ready.
+  </p>
+  <p>
+    For now, you can track the progress of a build by polling either the&nbsp;
+    <a href="#get-deployment-build-logs">build logs for a deployment</a> or the&nbsp;
+    <a href="#get-deployment-details">deployment details</a> API endpoints.
+  </p>
+</OpenApiEndpoint>
+
+<!-- deno-fmt-ignore-end -->
+
+### Compiler options
+
+The `compilerOptions` key of the `POST` body sent with a deployment creation
+request can override the options usually configured
+[here in deno.json](/runtime/manual/getting_started/configuration_file#compileroptions).
+Compiler options will determine how your application's TypeScript code will be
+processed.
+
+If `null` is provided, Deploy will attempt to discover a `deno.json` or
+`deno.jsonc` within the assets of your deployment (see **Deployment assets**
+below). If an empty object `{}` is provided, Deploy will use default TypeScript
+configuration.
+
+### Deployment assets
+
+The assets associated with a deployment are the code and static files that drive
+the behavior of the deployment and handle incoming requests. In JSON body sent
+with a `POST` request to this endpoint, you will include an `assets` attribute
+that contains keys that represent the file path to a particular asset.
+
+So for example - a file that would live in a deployment directory under
+`server/main.ts` would use that path as the key for the asset.
+
+An asset has a `kind` attribute associated with it, which can be one of:
+
+- `file` - an actual file associated with the deployment
+- `symlink` - a [symbolic link](https://en.wikipedia.org/wiki/Symbolic_link) to
+  another file in the deployment
+
+File assets also have a `content` property, which as you might imagine, is the
+actual contents of the file. These assets also have an `encoding` property,
+which indicates whether the content is encoded as `utf-8` (plain text) or
+`base64` for
+[base64 encoded content](https://developer.mozilla.org/en-US/docs/Glossary/Base64).
+
+To prevent the need to re-upload files that very seldom change, you can also
+specify a `gitSha1` attribute, which is a `SHA-1` hash of the content that was
+previously uploaded for the specified asset.
+
+Below is an example of `assets` that could be used to set up a deployment.
+
+```json
+{
+  "assets": {
+    "main.ts": {
+      "kind": "file",
+      "content": "Deno.serve((req: Request) => new Response(\"Hello World\"));",
+      "encoding": "utf-8"
+    },
+    "images/cat1.png": {
+      "kind": "file",
+      "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk",
+      "encoding": "base64"
+    },
+    "images/cat2.png": {
+      "kind": "file",
+      "gitSha1": "5c4f8729e5c30a91a890e24d7285e89f418c637b"
+    },
+    "symlink.png": {
+      "kind": "symlink",
+      "target": "images/cat1.png"
+    }
+  }
+}
+```
+
+## Get deployment details
+
+<OpenApiEndpoint path="/deployments/{deploymentId}" method="get">
+  Get details for a deployment with the given ID. This endpoint can be polled
+  to track the results of a serverless app deployment.
+</OpenApiEndpoint>
+
+## Get deployment build logs
+
+<OpenApiEndpoint path="/deployments/{deploymentId}/build_logs" method="get">
+  Get build logs for the deployment specified by ID. You can use this
+  information to check on the current status of a build, or to figure out
+  what went wrong in the case of a failure.
+  <br/><br/>
+  The response format can be controlled by the <code>Accept</code> header. If&nbsp;
+  <code>application/x-ndjson</code> is specified, the response will be a stream
+  of newline-delimited JSON objects. Otherwise it will be a JSON array of
+  objects.
+</OpenApiEndpoint>
+
+## Get deployment app logs
+
+<OpenApiEndpoint path="/deployments/{deploymentId}/app_logs" method="get">
+  Get execution logs of a deployment. This API can return either past logs or
+  real-time logs depending on the presence of the <code>since</code> and&nbsp;
+  <code>until</code> query parameters. If at least one of them is provided,
+  past logs are returned. Otherwise real-time logs are returned.
+  <br/><br/>
+  Also, the response format can be controlled by the <code>Accept</code>&nbsp;
+  header. If <code>application/x-ndjson</code> is specified, the response will
+  be a stream of newline-delimited JSON objects. Otherwise, it will be a JSON
+  array of objects.
+</OpenApiEndpoint>
diff --git a/deploy/api/rest/domains.md b/deploy/api/rest/domains.md
@@ -0,0 +1,60 @@
+import OpenApiEndpoint from "@site/src/components/OpenApiEndpoint";
+
+# Domains
+
+Custom domains can be used to give your deployments a unique URL.
+
+## List an organization's domains
+
+<OpenApiEndpoint path="/organizations/{organizationId}/domains" method="get">
+  Get a list of domains associated with an organization. Links to the first,
+  last, next, and previous pages of results are found in the <code>Link</code>
+  &nbsp;header of the response.
+</OpenApiEndpoint>
+
+## Add a domain to an organization
+
+<OpenApiEndpoint path="/organizations/{organizationId}/domains" method="post">
+  Add a new domain to the specified organization. Before use, added domain
+  needs to be verified, and TLS certificates for the domain need to be
+  provisioned.
+</OpenApiEndpoint>
+
+## Get a domain by ID
+
+<OpenApiEndpoint path="/domains/{domainId}" method="get">
+  Get metadata about a domain by the given ID.
+</OpenApiEndpoint>
+
+## Associate a domain with a deployment
+
+<OpenApiEndpoint path="/domains/{domainId}" method="patch">
+  With this API endpoint, you can associate or disassociate a domain with a
+  deployment. Domain association is required in order to serve the deployment
+  on the domain.
+</OpenApiEndpoint>
+
+## Delete a domain
+
+<OpenApiEndpoint path="/domains/{domainId}" method="delete">
+  Delete a domain by the given ID.
+</OpenApiEndpoint>
+
+## Verify a domain
+
+<OpenApiEndpoint path="/domains/{domainId}/verify" method="post">
+  This API endpoint triggers the ownership verification of a domain. It should
+  be called after necessary DNS records are properly set up.
+</OpenApiEndpoint>
+
+## Upload TLS certificate for a domain
+
+<OpenApiEndpoint path="/domains/{domainId}/certificates" method="post">
+  Upload TLS certificates for your domain.
+</OpenApiEndpoint>
+
+## Provision TLS certificates for a domain
+
+<OpenApiEndpoint path="/domains/{domainId}/certificates/provision" method="post">
+  Provision TLS certificates for your domain.
+</OpenApiEndpoint>
diff --git a/deploy/api/rest/images/org-id.png b/deploy/api/rest/images/org-id.png
diff --git a/deploy/api/rest/index.md b/deploy/api/rest/index.md
@@ -0,0 +1,63 @@
+# Deno Deploy REST API
+
+Developers can provision projects, domains, KV databases, and other resources
+using the Deno Deploy REST API. This API is most often used to implement
+[Subhosting](/deploy/manual/subhosting), a use case of Deno Deploy where you can
+run untrusted code on behalf of your users in the cloud.
+
+[Refer to the manual](/deploy/manual/subhosting) to learn more about Subhosting.
+
+## Endpoint and authentication
+
+The base URL for the Deno Deploy REST API v1 is below.
+
+```
+https://api.deno.com/v1/
+```
+
+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);
+```
+
+## OpenAPI specification and tooling
+
+The [OpenAPI specification](https://www.openapis.org/) for the Deploy API can be
+found here:
+
+```
+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/deploy/api/rest/organizations.md b/deploy/api/rest/organizations.md
@@ -0,0 +1,67 @@
+import OpenApiEndpoint from "@site/src/components/OpenApiEndpoint";
+
+# Organizations
+
+Organizations are a container for projects, domains, and KV databases. New
+organizations can be created in the
+[Deno Deploy dashboard](https://dash.deno.com). The access tokens created for
+your account may make changes to any of the organizations to which you have
+access.
+
+## Get organization details
+
+<OpenApiEndpoint path="/organizations/{organizationId}" method="get">
+  Get meta information about your organization, passing in your
+  unique ID as a path parameter.
+</OpenApiEndpoint>
+
+## Get analytics for organization
+
+<OpenApiEndpoint path="/organizations/{organizationId}/analytics" method="get">
+  Get analytics information for an organization.
+</OpenApiEndpoint>
+
+## List projects for an organization
+
+<OpenApiEndpoint path="/organizations/{organizationId}/projects" method="get">
+  Get a paginated list of Projects for an organization. Links to the first,
+  last, next, and previous pages of results are found in the <code>Link</code>
+  &nbsp;header of the response.
+</OpenApiEndpoint>
+
+## Create a new project for an organization
+
+<OpenApiEndpoint path="/organizations/{organizationId}/projects" method="post">
+  Create a new project within the given organization. A project is a container
+  for deployments, and can be associated with domains and KV databases.
+</OpenApiEndpoint>
+
+## List an organization's KV databases
+
+<OpenApiEndpoint path="/organizations/{organizationId}/databases" method="get">
+  Get a list of KV databases associated with an organization. Links to the first,
+  last, next, and previous pages of results are found in the <code>Link</code>
+  &nbsp;header of the response.
+</OpenApiEndpoint>
+
+## Create a KV database for an organization
+
+<OpenApiEndpoint path="/organizations/{organizationId}/databases" method="post">
+  Create a new KV database associated with an organization.
+</OpenApiEndpoint>
+
+## List an organization's domains
+
+<OpenApiEndpoint path="/organizations/{organizationId}/domains" method="get">
+  Get a list of domains associated with an organization. Links to the first,
+  last, next, and previous pages of results are found in the <code>Link</code>
+  &nbsp;header of the response.
+</OpenApiEndpoint>
+
+## Add a domain to an organization
+
+<OpenApiEndpoint path="/organizations/{organizationId}/domains" method="post">
+  Add a new domain to the specified organization. Before use, added domain
+  needs to be verified, and TLS certificates for the domain need to be
+  provisioned.
+</OpenApiEndpoint>
diff --git a/deploy/api/rest/projects.md b/deploy/api/rest/projects.md
@@ -0,0 +1,40 @@
+import OpenApiEndpoint from "@site/src/components/OpenApiEndpoint";
+
+# Projects
+
+Projects are a container for deployments, and can be associated with domains and
+KV databases in an organization.
+
+## Get project details
+
+<OpenApiEndpoint path="/projects/{projectId}" method="get">
+  Get meta information about a project by unique ID.
+</OpenApiEndpoint>
+
+## Update project details
+
+<OpenApiEndpoint path="/projects/{projectId}" method="patch">
+  Update meta information about a project.
+</OpenApiEndpoint>
+
+## Delete a project
+
+<OpenApiEndpoint path="/projects/{projectId}" method="delete">
+  Delete a project by unique ID.
+</OpenApiEndpoint>
+
+## Get project analytics
+
+<OpenApiEndpoint path="/projects/{projectId}/analytics" method="get">
+  Get analytics data for the specified project. The analytics are returned as
+  time series data in 15 minute intervals, with the <code>time</code> field
+  representing the start of the interval.
+</OpenApiEndpoint>
+
+## Get project deployments
+
+<OpenApiEndpoint path="/projects/{projectId}/deployments" method="get">
+  Get a paginated list of deployments belonging to the specified project. The
+  URLs for the next, previous, first, and last page are returned in the
+  <code>Link</code> header of the response if needed.
+</OpenApiEndpoint>
diff --git a/deploy/manual/subhosting/domains.md b/deploy/manual/subhosting/domains.md
@@ -0,0 +1,6 @@
+# Working with custom domains
+
+TODO - talk about provisioning domains and associating them with deployments.
+
+For now, reference:
+https://github.com/denoland/deploy-api/blob/main/samples.ipynb