zuplo 6.67.32 → 6.68.0

package/docs/articles/accounts/zuplo-api-keys.mdx

@@ -0,0 +1,94 @@
+---
+title: Zuplo API Keys
+sidebar_label: API Keys
+---
+
+The [Zuplo Developer API](https://dev.zuplo.com) allows you to programmatically
+interact with Zuplo. To access the API, you need to create an API key.
+
+API keys are used to authenticate requests to the Zuplo API. They're unique to
+your account and should be kept secret. Don't share your API key in publicly
+accessible areas such as GitHub repositories.
+
+## Creating an API Key
+
+To start, navigate to the account settings page by clicking your user icon in
+the top right corner of the screen and selecting "Settings" from the dropdown
+menu. Click the **API Keys** tab to view the API keys in your account that you
+have access to.
+
+![API Keys](../../../public/media/zuplo-api-keys/image.png)
+
+:::note{title="Required Role"}
+
+Account admins can view and manage all API keys in the account. Developers can
+only view their own API keys. Members don't have access to API keys.
+
+:::
+
+Select the "Create API Key" button to create a new API key. You can enter a
+label, expiration, and select the permissions for your new API key.
+
+<EnterpriseFeature name="Fine-grained API Key Management" />
+
+![Create API Key](../../../public/media/zuplo-api-keys/image-1.png)
+
+## Editing an API Key
+
+API Keys are immutable once created. If you need to change the permissions you
+will need to create a new API key.
+
+## Deleting an API Key
+
+API Keys can be deleted by selecting the delete button on the list page or by
+opening the details page for the key and clicking the **Delete** button at the
+bottom of the page.
+
+![Delete API Key](../../../public/media/zuplo-api-keys/image-2.png)
+
+## API Key Permissions
+
+<EnterpriseFeature name="Fine-grained API Key Management" />
+
+The following table outlines the permissions available to each API key.
+
+### Project Access
+
+API Keys can be scoped to all projects or specific projects in the account.
+Selecting All Projects will also grant all project level permissions to that
+key. If you want to customize the project level permissions, scope the key to
+one or more projects.
+
+![Project Access](../../../public/media/zuplo-api-keys/image-3.png)
+
+### Environment Access
+
+API Keys can be scoped to all environments or specific environments within the
+projects they have access to. You can select one or more environments. For
+example, if you want to restrict a key to only have access to only access
+preview and development environments, you can select only those two
+environments.
+
+![Environment Access](../../../public/media/zuplo-api-keys/image-4.png)
+
+### Project permissions
+
+When API Keys are scoped to specific projects, you can select the permissions
+the key has in that project. For each permission select the level of access
+desired from the drop down.
+
+![Project permissions](../../../public/media/zuplo-api-keys/image-5.png)
+
+### Account permissions
+
+API Keys can be granted account level permissions. These permissions are for
+account level resources like custom domains, tunnels, etc. For each permission
+select the level of access desired from the drop down.
+
+![Account permissions](../../../public/media/zuplo-api-keys/image-6.png)
+
+When selecting permissions for API Key Buckets or Monetization Buckets, the
+environment type scope is also applied. For example, if your key has access to
+preview environments and has Read and Write access to API Key buckets, that key
+can only read and write to API Key buckets in the preview environments - it
+can't modify buckets used in production environments.

package/docs/articles/add-api-to-backstage.mdx

@@ -0,0 +1,216 @@
+---
+title: Add Your Zuplo API to Backstage
+sidebar_label: "Backstage Integration"
+description:
+  Learn how to integrate your Zuplo API into Backstage by adding OpenAPI spec
+  handlers and configuring catalog entries.
+tags:
+  - openapi
+  - backends
+  - integrations
+---
+
+In this guide, we'll walk you through the steps to add your Zuplo API to
+[Backstage](https://backstage.io/).
+
+## 1/ Add the OpenAPI Spec Handler
+
+Backstage allows you to document
+[API entities](https://backstage.io/docs/features/software-catalog/descriptor-format/#kind-api)
+using an OpenAPI file. Although Zuplo is OpenAPI based, you can't directly use
+your `routes.oas.json` file, as it's missing details about your API. Instead,
+you will need to use the public-ready version of your spec, by adding an
+[OpenAPI Spec Handler](../handlers/openapi.mdx).
+
+Add a new route with the path `/openapi`, and select the `OpenAPI Spec Handler`
+from the Request Handler selector. Save your changes and commit them to your
+production branch. If you haven't already connected your Zuplo API to a GitHub
+repository, you can follow
+[these instructions](./step-4-deploying-to-the-edge.mdx) to do so. Once your
+Zuplo API is redeployed, you should now be able to retrieve your public-ready
+OpenAPI file by hitting `https://<your-prod-zuplo-api-domain>/openapi`.
+
+![Zuplo route](../../public/media/add-api-to-backstage/image-3.png)
+
+## 2/ Add Zuplo to your `reading.allowed` list
+
+Navigate to the `app-config.yaml` file in your backstage repository. You will
+need to allow backstage to call Zuplo's domain to fetch the OpenAPI file. Add
+the following code:
+
+```yaml
+backend:
+  reading:
+    allow:
+      - host: "*.zuplo.dev"
+      - host: "*.zuplo.app"
+```
+
+If you are using a [custom domain](./custom-domains.mdx) on your Zuplo API - you
+will need to add that domain in the list above.
+
+## 3/ Add your Zuplo API to your Backstage Catalog
+
+The most direct way to add your Zuplo API to backstage is by adding an entry to
+your backstage service's `entities.yaml` file.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: backstage-sample-api # Your API name
+  annotations:
+    # Your github project slug Ex. org/repo-name
+    github.com/project-slug: zuplo-samples/backstage-sample-api
+spec:
+  type: openapi
+  lifecycle: experimental # Change to match your backstage project
+  owner: guests # Change to match your backstage project
+  system: examples # Change to match your backstage project
+  definition:
+    # Change to match your Zuplo API
+    $text: https://backstage-sample-api-main-821019a.zuplo.app/openapi
+```
+
+Once you've added the API component, you must link it to an existing component.
+For example, if your website provides APIs, you would add the following
+
+```yaml
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: example-website
+spec:
+  type: website
+  lifecycle: experimental
+  owner: guests
+  system: examples
+  providesApis: [backstage-sample-api] # This must match the metadata.name of the entity
+---
+```
+
+You should now be able to see your API under the APIs tab in Backstage. If you
+navigate to your API and click the **DEFINITION** tab - you can even preview
+your OpenAPI spec.
+
+![OpenAPI spec](../../public/media/add-api-to-backstage/image-6.png)
+
+Congratulations! You've successfully added your Zuplo API to Backstage. You can
+repeat the steps above for all of your OpenAPI files.
+
+## Optional: Reusing your API across Backstage catalogs
+
+If you don't wish to directly add your Zuplo API to your backstage
+`entities.yaml`, you can instead add the entity definition to your Zuplo
+repository directly, and sync it with backstage using their GitHub integration.
+You will still need to follow steps 1 & 2 from the guide above.
+
+### 1/ Add `catalog-info.yaml` to your Zuplo Repository
+
+In your Zuplo repository, add a file named `catalog-info.yaml` and fill it with
+the following
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: backstage-sample-api # Your API name
+  annotations:
+    # Your github project slug Ex. org/repo-name
+    github.com/project-slug: zuplo-samples/backstage-sample-api
+spec:
+  type: openapi
+  lifecycle: experimental # Change to match your backstage project
+  owner: guests # Change to match your backstage project
+  system: examples # Change to match your backstage project
+  definition:
+    # Change to match your Zuplo API
+    $text: https://backstage-sample-api-main-821019a.zuplo.app/openapi
+```
+
+Save and commit this file.
+
+### 2/ Add your API Component to Backstage
+
+You can register existing APIs in your catalog directly from Backstage. Navigate
+to the APIs tab, and click **REGISTER EXISTING API**.
+
+![APIs list](../../public/media/add-api-to-backstage/image-5.png)
+
+When prompted for the component URL, enter the GitHub URL of your
+`catalog-info.yaml` file (ex.
+https://github.com/AdrianMachado/adrian-api/blob/main/catalog-info.yaml).
+
+![Adding the GitHub URL](../../public/media/add-api-to-backstage/image-4.png)
+
+Complete registration of your API. If you run into issues connecting your
+repository, see the [troubleshooting guide](#troubleshooting).
+
+### 3/ Link the API to a component
+
+You should now be able to see your API under the APIs tab in Backstage. If your
+API is associated with another entity, you will need to link to that entity as
+follows:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: System
+metadata:
+  name: examples
+spec:
+  owner: guests
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: example-website
+spec:
+  type: website
+  lifecycle: experimental
+  owner: guests
+  system: examples
+  providesApis: [<YOUR_API_NAME>] # This must match the metadata.name from step 1
+```
+
+## Troubleshooting
+
+### Can't connect to GitHub
+
+If your repository isn't public and you haven't already configured GitHub
+authentication -
+[follow the GitHub auth guide](https://backstage.io/docs/getting-started/config/authentication).
+You will likely want to add sign-in support as a part of your Backstage setup,
+to authenticate your users. In your `app-config.yaml` add:
+
+```yaml
+auth:
+  allowGuestAccess: true
+  environment: development
+  providers:
+    github:
+      development:
+        clientId: ${GITHUB_CLIENT_ID}
+        clientSecret: ${GITHUB_CLIENT_SECRET}
+        signIn:
+          resolvers:
+            - resolver: emailMatchingUserEntityProfileEmail
+            - resolver: usernameMatchingUserEntityName
+```
+
+Additionally, in your `index.ts` file, add the following line before calling
+`backend.start()`
+
+```typescript
+backend.add(import("@backstage/plugin-auth-backend-module-github-provider"));
+```
+
+This isn't well documented by Backstage - any issues should be directed
+[to them](https://github.com/backstage/backstage/issues).
+
+### Backstage hosted on Roadie.io
+
+If you are using a managed version of Backstage from services like Roadie.io -
+you will need to follow their
+[official docs](https://roadie.io/docs/details/openapi-specs/) for OpenAPI. We
+don't guarantee support for these platforms.

package/docs/articles/advanced-path-matching.mdx

@@ -0,0 +1,139 @@
+---
+title: Advanced Path Matching
+sidebar_label: "Advanced Path Matching"
+description:
+  Learn how to use URLPattern for advanced path matching with dynamic
+  parameters, regular expressions, and wildcards in Zuplo.
+tags:
+  - openapi
+  - custom-code
+---
+
+By default, path matching in Zuplo uses the OpenAPI slug format, for example
+`/pizza/{size}` where **size** would be a URL parameter, with the value passed
+into the runtime as `request.params.size` property.
+
+However, you can opt to use a more advanced path matching approach based on the
+web standard
+[URLPattern](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern).
+
+In order to use URLPattern matching you must set your route's
+`x-zuplo-path.pathMode` to `url-pattern`.
+
+The URLPattern matching mode can be set in the UI as shown below:
+
+![Route ](../../public/media/advanced-path-matching/image.png)
+
+Alternatively, you can set it in your OpenAPI file as follows:
+
+```json {4-6} title="config/routes.oas.json"
+{
+  "paths": {
+    "/files/:path*": {
+      "x-zuplo-path": {
+        "pathMode": "url-pattern"
+      }
+    }
+  }
+}
+```
+
+The most basic path is `/` which will simple match the root path. You can add
+other static paths like `/foo` and `/foo/bar`
+
+:::tip
+
+Use [URLPattern.com](https://urlpattern.com) to test your URL Patterns in the
+browser.
+
+:::
+
+## Trailing Slashes
+
+In URLPattern, trailing slashes aren't accepted unless explicitly specified. For
+example:
+
+- `/cars/:manufacturer`
+
+Would match `/cars/ford` but not `/cars/ford/`. If you want to support this you
+must add a little regex to the end of your path, for example -
+`/cars/:manufacturer{/}?`
+
+Will match both example routes given above.
+
+## Dynamic Paths
+
+URLPattern supports dynamic matching including a feature that will parameterize
+parts of the URL. For example:
+
+Path: `/products/:productId/sizes/:size` will match the following paths
+
+`/products/pizza/size/small` and set the `params` object on `request` to:
+
+```json
+{
+  "productId": "pizza",
+  "size": "small"
+}
+```
+
+:::tip
+
+Query-strings (or search parameters) won't affect path matching.
+
+:::
+
+## Regular Expressions and Wildcards
+
+You can also use regular expressions in your paths. They must be contained in
+`()`.
+
+**Examples**
+
+Path `/(.*)` will match anything.
+
+:::note
+
+This is a true wildcard route and can be used for custom 404s by making this the
+last route in your OpenAPI file (and matching all methods).
+
+:::
+
+Path `/(a?b)` will match either `/ab` or `/b`.
+
+Path `/main/(a|b)` will match `/main/a` or `/main/b`.
+
+Path `/icon-(\d++).png` will match `/icon-1234.png` or any other series of
+digits for 1234.
+
+## Named groups
+
+You can also name your regexp groups so that they appear as named parameters.
+
+`name:(.*)` - will match a wildcard and call the parameter.
+
+For example, the path `products/:productId/icons/icon-:imageIndex(\d+).png` will
+match `/products/pizza/icons/icon-2.png` and produce a `request.params` object
+as follows:
+
+```json
+{
+  "productId": "pizza",
+  "imageIndex": "2"
+}
+```
+
+You can write a [URL Rewrite](../handlers/url-rewrite.mdx) that takes an
+incoming wildcard and appends it to the backend request, for example Path:
+`/foo/bar:path(/.*)` Incoming URL: `/foo/bar/apple/banana` URL Rewrite Pattern:
+`https://example.com/x${params.path}` Outgoing URL:
+`https://example.com/x/apple/banana`
+
+## Not supported
+
+Note that not all regex features are available, us of the following will either
+be ignored or result in an error, including
+
+- `(?:...)` - named matches
+- `^` or `$` - start or end of string
+- `[abc]` - character classes

package/docs/articles/api-key-administration.mdx

@@ -0,0 +1,47 @@
+---
+title: Managing API Keys in the Portal
+sidebar_label: Managing Keys
+---
+
+API Key Consumers can be managed in the Zuplo Portal's **Services** section.
+Each project is created with three API Key Buckets - one for production, one
+shared by preview environments, and one for development (working copy)
+environments.
+
+![Services](../../public/media/api-key-administration/image.png)
+
+You can view the buckets for each environment or for all environments using the
+drop down.
+
+![Environment Selection](../../public/media/api-key-administration/image-1.png)
+
+To open the API Key Bucket for an environment, click the **Configure** button.
+
+![Configure](../../public/media/api-key-administration/image-2.png)
+
+When you first open the API Key Bucket, you won't have any API Keys created.
+
+![Empty API Key Bucket](../../public/media/api-key-administration/image-3.png)
+
+To add a new API Key Consumer click the **Create Consumer** button and complete
+the form.
+
+![New API Key Consumer](../../public/media/api-key-administration/image-4.png)
+
+Once a consumer is created, you can view or copy the API Key by clicking the
+icons shown.
+
+![Copy or View](../../public/media/api-key-administration/image-5.png)
+
+If you're using the Zuplo [Developer Portal](../dev-portal/introduction.mdx),
+we've an integration with the API Key API that allows developers to access their
+API keys, create new ones and delete them. To enable this, you must assign one
+or more managers, via e-mail, to be a manager for your API Key Consumer. This is
+optional if you aren't using the
+[Developer Portal](../dev-portal/introduction.mdx).
+
+You can assign managers in the Zuplo Portal (portal.zuplo.com) or via the API.
+
+If you want to automatically create an API Key for a customer automatically when
+they sign into your developer portal using Auth0,
+[follow this tutorial](../dev-portal/dev-portal-create-consumer-on-auth.mdx).