zuplo 6.67.32 → 6.68.0

package/docs/articles/rename-or-move-project.mdx

@@ -0,0 +1,39 @@
+---
+title: How to rename or move a project
+sidebar_label: Rename/Move Project
+---
+
+Projects can't be moved between accounts or renamed in Zuplo but there is an
+easy workaround using Source Control.
+
+If the project you want to move or rename isn't already connected to source
+control then
+[follow our GitHub integration guide](/docs/articles/source-control). This will
+copy the contents of your project to a GitHub repository.
+
+If your project is already connected to Source Control (or you just connected it
+above) the next step is to push any changes you want to be included in when you
+move to a different project.
+
+If you're confident all your code is stored safely in the repository you can now
+disconnect the project from Source Control.
+
+![Disconnect Project](../../public/media/rename-or-move-project/image.png)
+
+Next create a new project in the correct account if moving accounts or with the
+correct name. Choose the `Advanced` option on the new project dialog.
+
+![Import existing project](../../public/media/source-control/image-1.png)
+
+You should see a list of organizations and repositories - pick the source
+repository you wanted to move and click **Create Project from repository**.
+
+Your new project will now be connected to this repository and ready to go.
+
+NOTE - assets and data that isn't 'code' and stored in the repository won't be
+moved. Things that won't be moved when renaming a project include:
+
+- API Key consumers
+- Environment variable values
+- Permissions / Project Members
+- Custom Domains (contact us to move these for you)

package/docs/articles/rick-and-morty-api-developer-portal-example.mdx

@@ -0,0 +1,23 @@
+---
+title: Rick and Morty Developer Portal and Documentation
+sidebar_label: "Example: Rick and Morty API"
+description:
+  Learn how to use the Rick and Morty REST API to access characters, locations,
+  and episodes from the TV show.
+tags:
+  - dev-portal
+  - openapi
+---
+
+This is an example API proxied via Zuplo - these docs are generated based on the
+gateway configuration for the Rick and Morty API.
+[Example Documentation](https://rickandmorty.zuplo.io/)
+
+The Rick and Morty API is a REST(ish) API based on the television show Rick and
+Morty. It provides access to hundreds of characters, images, locations and
+episodes. The Rick and Morty API is filled with canonical information as seen on
+the TV show. Full credit to the original and upstream API, which is available at
+rickandmortyapi.com.
+
+> "I'm A Scientist; Because I Invent, Transform, Create, And Destroy For A
+> Living, And When I Don't Like Something About The World, I Change It."

package/docs/articles/routing.mdx

@@ -0,0 +1,193 @@
+---
+title: Zuplo Routing
+sidebar_label: Routing
+---
+
+Zuplo's routing system is designed to be simple and powerful, allowing you to
+define how requests are handled and processed. The routing system is based on
+the OpenAPI 3.1 specification, which provides a standard way to describe your
+API endpoints.
+
+## Routing Basics
+
+Zuplo uses the OpenAPI document to define the routes for your API. Each route is
+defined by a path and an HTTP method (GET, POST, PUT, DELETE, etc.). The OpenAPI
+document can be edited directly in Zuplo or imported from an external source.
+
+## Path Modes
+
+Zuplo supports two path modes:
+
+- **OpenAPI Mode**: This mode is the default and allows you to define routes
+  using OpenAPI paths and
+  [path parameters](https://swagger.io/docs/specification/v3_0/describing-parameters/#path-parameters).
+  For example, `/users/{userId}` would match any URL that starts with `/users/`
+  and has a user ID at the end. This is the recommended mode for most use cases,
+  as it provides a clear and standardized way to define your API routes. This is
+  the default mode in both the Zuplo UI and when a mode isn't explicitly set in
+  an OpenAPI document.
+- **URL Pattern Mode**: This mode allows you to define routes using the
+  web-standard
+  [URLPattern](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern). For
+  example, `/users/:userId` would match any URL that starts with `/users/` and
+  has a user ID at the end. This mode is more powerful and flexible, allowing
+  you to use regular expressions and other advanced matching techniques. You can
+  switch to URL Pattern mode by setting the `x-zuplo-path` property in your
+  OpenAPI document.
+
+## Path Matching & Order
+
+Zuplo uses the OpenAPI document to determine how to match incoming requests to
+the defined routes. The matching process is based on the HTTP method and the
+path of the request. Zuplo will look for a matching route in the OpenAPI
+document and will use the corresponding request handler to process the request.
+
+### Route Matching Order
+
+Routes are matched in the order they're defined in the OpenAPI document and the
+alphabetical order the OpenAPI documents are defined in your project. For
+example, if you have two OpenAPI files, `file1.json` and `file2.json`,
+`file1.json` will be matched first. This is particularly important when using
+advanced matching like RegEx or URL Pattern matching, as the order of the routes
+can affect which route is matched for a given request. If you have two routes
+that could match the same request, the first one defined in the OpenAPI document
+will be used.
+
+### Customizing Route Order
+
+To customize or change the order of route matching within a single OpenAPI file,
+reorder the path entries in the `paths` object. The first path defined in the
+file will be matched first, followed by the second, etc.
+
+For example, if you want `/users/admin` to be matched before `/users/{userId}`,
+place it first in your `routes.oas.json`:
+
+```json
+{
+  "paths": {
+    "/users/admin": {
+      "get": {
+        "operationId": "get-admin-user"
+      }
+    },
+    "/users/{userId}": {
+      "get": {
+        "operationId": "get-user"
+      }
+    }
+  }
+}
+```
+
+In this example, requests to `/users/admin` will match the first route, while
+requests to `/users/123` will match the second route. If the order were
+reversed, `/users/admin` would incorrectly match the `{userId}` parameter route.
+
+:::tip
+
+When organizing routes, place more specific paths before more general ones to
+ensure correct matching. Wildcard routes and catch-all patterns should typically
+be placed last.
+
+:::
+
+## Path Parameters
+
+Path parameters are variables in the URL path that can be used to capture
+dynamic values. For example, in the path `/users/{userId}`, `{userId}` is a path
+parameter that can be replaced with an actual user ID. Zuplo supports path
+parameters in both OpenAPI and URL Pattern modes. Path parameters are defined in
+the OpenAPI document using curly braces `{}`. For example, the path
+`/users/{userId}` defines a path parameter called `userId`. You can use path
+parameters in your request handlers to access the values captured by the
+parameters. For example, in a request handler for the path `/users/{userId}`,
+you can access the `userId` parameter using the `request.params` object:
+
+```ts
+import { ZuploRequest, ZuploContext } from "@zuplo/runtime";
+import { getUserById } from "./userService";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const userId = request.params.userId;
+  const user = await getUserById(userId);
+  return context.json(user);
+}
+```
+
+In this example, the `userId` parameter is extracted from the request and used
+to fetch the user from an external data source or API in the `getUserById`
+function.
+
+URLPattern mode also supports path parameters, but they're defined using a colon
+`:` instead of curly braces `{}`. For example, the path `/users/:userId` defines
+a path parameter called `userId`. You can use path parameters in your request
+handlers in the same way as in OpenAPI mode.
+
+## Path Matching Examples
+
+### OpenAPI Mode
+
+The example below shows how to define a route in OpenAPI mode with a simple path
+and `userId` parameter.
+
+```json
+{
+  "paths": {
+    "/users/{userId}": {
+      "get": {
+        "operationId": "get-user"
+      }
+    }
+  }
+}
+```
+
+Parameters can be defined anywhere in a path, for example, you could have a path
+like `/users/{userId}/posts/{postId}`. This would match any URL that starts with
+`/users/` and has a user ID and post ID at the end.
+
+Paths don't need to be defined using common REST principles. You are free to
+structure your paths however you prefer. For example, `/users/get({userId})` is
+a valid OpenAPI path and would still match the `userId` parameter.
+
+:::caution{title="Special Characters"}
+
+The handling of special characters in the path has changed with
+[Compatibility Date 2025-02-06](../programmable-api/compatibility-dates.mdx#special-characters-in-openapi-format-urls)
+
+:::
+
+### URL Pattern Mode
+
+The example below shows how to define a route in OpenAPI mode with a simple path
+and `userId` parameter.
+
+```json
+{
+  "paths": {
+    "/users/:userId": {
+      "get": {
+        "operationId": "get-user"
+      }
+    }
+  }
+}
+```
+
+In addition to the simple parameter patterns, you can also use RegEx patterns. A
+common use of this is to create wildcard routes. For example, the path
+`/users/(.*)` would match any URL that starts with `/users/` and has any value
+after it. This is useful for creating catch-all routes or wildcard routes that
+can handle multiple paths.
+
+```json
+{
+  "paths": {
+    "/users/(.*)": {
+      "get": {
+        "operationId": "get-user"
+      }
+    }
+  }
+}
+```