Added local quickstart to sidebar

docs/articles/add-api-to-backstage.md

@@ -18,7 +18,7 @@ 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.md) to do so. Once your
+[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`.
 

docs/articles/api-key-management.md

@@ -15,7 +15,7 @@ minutes. There are several benefits to using Zuplo's API Key solution including
 :::tip
 
 To start using Zuplo API Keys in only a few minutes
-[see the quickstart](../articles/step-3-add-api-key-auth.md).
+[see the quickstart](../articles/step-3-add-api-key-auth.mdx).
 
 :::
 
@@ -42,7 +42,7 @@ Zuplo manages all the complexity of replication, caching, and verifying your API
 keys so you don't have to.
 
 Adding API Key authentication using Zuplo takes only a few minutes.
-[See the quickstart to get started](../articles/step-3-add-api-key-auth.md).
+[See the quickstart to get started](../articles/step-3-add-api-key-auth.mdx).
 
 ## Key Concepts
 

docs/articles/source-control.md

@@ -27,7 +27,7 @@ benefits, including:
   adding a branch or making a commit.
 
 For full instructions on setting up GitHub see
-[the quickstart tutorial](../articles/step-4-deploying-to-the-edge.md).
+[the quickstart tutorial](../articles/step-4-deploying-to-the-edge.mdx).
 
 ## Connecting Existing Repositories
 

docs/articles/step-1-setup-basic-gateway-local.md → docs/articles/step-1-setup-basic-gateway-local.mdx

@@ -1,7 +1,12 @@
 ---
-title: Step 1 - Setup a Basic Gateway (Local)
+title: Step 1 - Setup a Basic Gateway
 ---
 
+<QuickstartPicker
+  mode="local"
+  alternateLink="/articles/step-1-setup-basic-gateway"
+/>
+
 In this tutorial we'll setup a simple gateway using Zuplo's local development.
 We'll use a simple origin API at [echo.zuplo.io](https://echo.zuplo.io). In
 later steps, we'll setup a Zuplo project and deploy it to the cloud.
@@ -122,4 +127,4 @@ later steps, we'll setup a Zuplo project and deploy it to the cloud.
 </Stepper>
 
 **NEXT** Try
-[Step 2 - Add Rate Limiting to your API](./step-2-add-rate-limiting.md).
+[Step 2 - Add Rate Limiting to your API](./step-2-add-rate-limiting.mdx).

docs/articles/step-1-setup-basic-gateway.md → docs/articles/step-1-setup-basic-gateway.mdx

@@ -3,6 +3,11 @@ title: Step 1 - Setup a Basic Gateway
 sidebar_label: "Step 1 - Setup Your Gateway"
 ---
 
+<QuickstartPicker
+  mode="portal"
+  alternateLink="/articles/step-1-setup-basic-gateway-local"
+/>
+
 In this tutorial we'll setup a simple gateway. We'll use a simple origin API at
 [getting-started.zuplo.io](https://getting-started.zuplo.io).
 
@@ -109,4 +114,4 @@ Note - Zuplo also supports building and running your API locally. To learn more
 </Stepper>
 
 **NEXT** Try
-[Step 2 - Add Rate Limiting to your API](./step-2-add-rate-limiting.md).
+[Step 2 - Add Rate Limiting to your API](./step-2-add-rate-limiting.mdx).

docs/articles/step-2-add-rate-limiting.md → docs/articles/step-2-add-rate-limiting-local.mdx

@@ -3,8 +3,13 @@ title: Step 2 - Add Rate Limiting
 sidebar_label: "Step 2 - Rate Limiting"
 ---
 
+<QuickstartPicker
+  mode="local"
+  alternateLink="/articles/step-2-add-rate-limiting"
+/>
+
 In this guide we'll add simple Rate Limiting to a route. If you don't have one
-ready, complete [Step 1](./step-1-setup-basic-gateway.md) first.
+ready, complete [Step 1](./step-1-setup-basic-gateway.mdx) first.
 
 Rate Limiting is one of our most popular **policies** - you should never ship an
 API without rate limiting because your customers or internal developers **will**

docs/articles/step-2-add-rate-limiting.mdx

@@ -0,0 +1,81 @@
+---
+title: Step 2 - Add Rate Limiting
+sidebar_label: "Step 2 - Rate Limiting"
+---
+
+<QuickstartPicker
+  mode="portal"
+  alternateLink="/articles/step-2-add-rate-limiting-local"
+/>
+
+In this guide we'll add simple Rate Limiting to a route. If you don't have one
+ready, complete [Step 1](./step-1-setup-basic-gateway.mdx) first.
+
+Rate Limiting is one of our most popular **policies** - you should never ship an
+API without rate limiting because your customers or internal developers **will**
+accidentally DoS your API; usually with a rogue `useEffect` call in React code.
+
+:::info{title="What's a Policy?"}
+
+[Policies](./policies.md) are modules that can intercept and transform an
+incoming request or outgoing response. Zuplo offers a wide range of policies
+built-in (including rate limiting) to save you time. You can check out
+[the full list](../policies.md).
+
+:::
+
+Zuplo offers a programmable approach to rate limiting that allows you to vary
+how rate limiting is applied for each customer, or request.s
+
+In this example, we'll add a simple IP based rate limiter, but you should look
+into dynamic rate limiting to see the full power of the world's best rate
+limiter.
+
+<Stepper>
+
+1.  Add the rate-limiting Policy
+
+        Navigate to your route in the **Route Designer** (**Code** > `routes.oas.json`),
+        click the **Policies** dropdown, then click **Add Policy** on the request
+        pipeline.
+
+        <ModalScreenshot>
+
+        ![Add policy](../../public/media/step-2-add-rate-limiting/image.png)
+
+        </ModalScreenshot>
+
+        Search for the rate limiting policy (not the "Complex" one) and click it.
+
+        <ModalScreenshot>
+
+        ![Add rate-limiting policy](../../public/media/step-2-add-rate-limiting/choose-rate-limiter.png)
+
+        </ModalScreenshot>
+
+        By default, the policy will rate limit based on the caller's IP address (as
+        indicated by the `rateLimitBy` field). It will allow 2 requests
+        (`requestsAllowed`) every 1 minute (`timeWindowMinutes`). You can explore the
+        rest of the policy's documentation and configuration in the right panel.
+
+        ![Rate limiting policy](../../public/media/step-2-add-rate-limiting/create-policy.png)
+
+        To apply the policy, click **OK**. Then, save your changes to redeploy.
+
+1.  Testing your Policy
+
+        Now try firing some requests against your API. You should receive a **429 Too
+        many requests** on your 3rd request.
+
+        <ModalScreenshot>
+
+        ![429 response](../../public/media/step-2-add-rate-limiting/test-api.png)
+
+        </ModalScreenshot>
+
+        Your rate limiting policy is now intercepting excess requests, protecting the
+        `getting-started` API.
+
+</Stepper>
+
+**NEXT** Try [Step 3 - Add API Key Authentication](./step-3-add-api-key-auth).

docs/articles/step-3-add-api-key-auth.md → docs/articles/step-3-add-api-key-auth-local.mdx

@@ -3,9 +3,14 @@ title: Step 3 - API Key Authentication
 sidebar_label: "Step 3 - API Key Auth"
 ---
 
+<QuickstartPicker
+  mode="local"
+  alternateLink="/articles/step-3-add-api-key-auth"
+/>
+
 In this guide we'll add API Key authentication to a route. You can do this for
 any Zuplo project but will need a route, consider completing
-[Step 1](./step-1-setup-basic-gateway.md) first.
+[Step 1](./step-1-setup-basic-gateway.mdx) first.
 
 API Key authentication is one of our most popular **policies** as implementing
 this authentication method is considered one of the easiest to use by developers
@@ -45,7 +50,7 @@ Let's get started.
    :::tip
 
    The API key authentication policy should usually be one of the first policies
-   executed. If you came here from [Step 2](./step-2-add-rate-limiting.md) then
+   executed. If you came here from [Step 2](./step-2-add-rate-limiting.mdx) then
    you will want to drag it above the rate limiting policy.
 
    :::

docs/articles/step-3-add-api-key-auth.mdx

@@ -0,0 +1,165 @@
+---
+title: Step 3 - API Key Authentication
+sidebar_label: "Step 3 - API Key Auth"
+---
+
+<QuickstartPicker
+  mode="portal"
+  alternateLink="/articles/step-3-add-api-key-auth-local"
+/>
+
+In this guide we'll add API Key authentication to a route. You can do this for
+any Zuplo project but will need a route, consider completing
+[Step 1](./step-1-setup-basic-gateway.mdx) first.
+
+API Key authentication is one of our most popular **policies** as implementing
+this authentication method is considered one of the easiest to use by developers
+but hard for API developers to get right. We also support JWT tokens and most
+other authentication methods.
+
+:::info{title="What's a Policy?"}
+
+[Policies](./policies.md) are modules that can intercept and transform an
+incoming request or outgoing response. Zuplo offers a wide range of policies
+built-in (including api key authentication) to save you time. You can check out
+[the full list](./policies.md).
+
+:::
+
+Let's get started.
+
+<Stepper>
+
+1. Add the API Key Authentication Policy
+
+   Navigate to your route in the **Route Designer** (**Code** >
+   `routes.oas.json`) and open the **Policies** section. Then click **Add
+   Policy**.
+
+   ![Add Policy](../../public/media/step-3-add-api-key-auth/image.png)
+
+   Search for the API key authentication policy, click on it, and then click OK
+   to accept the default policy JSON.
+
+   <ModalScreenshot>
+
+   ![Add API Key Authentication](../../public/media/step-3-add-api-key-auth/choose-policy.png)
+
+   </ModalScreenshot>
+
+   :::tip
+
+   The API key authentication policy should usually be one of the first policies
+   executed. If you came here from [Step 2](./step-2-add-rate-limiting.mdx) then
+   you will want to drag it above the rate limiting policy.
+
+   :::
+
+   ![reorder policies](../../public/media/step-3-add-api-key-auth/image-1.gif)
+
+   If you test your route, you should get a 401 Unauthorized response
+
+   ```json
+   {
+     "status": 401,
+     "title": "Unauthorized",
+     "type": "https://httpproblems.com/http-status/401"
+   }
+   ```
+
+2. Set up an API Key
+
+   In order to call your API, you need to configure an API consumer. Go to
+   **Services**, then click **Configure** on the "API Key Service".
+
+   ![API Key Service](../../public/media/step-3-add-api-key-auth/image-2.png)
+
+   Then click **Create Consumer**.
+
+   ![Create Consumer](../../public/media/step-2-add-api-key-auth/image-8.png)
+
+   Let's break down the configuration needed.
+   - Subject: Also known as `sub`. This is a unique identifier of the API
+     consumer. This is commonly the name of the user or organization consuming
+     your API
+   - Key managers: The email addresses of those who will be managing this API
+     key.
+   - Metadata: JSON metadata that will be made available to the runtime when a
+     key is used to authenticate. Common properties include the consumer's
+     subscription plan, organization, etc.
+
+   Go ahead and fill in `test-consumer` for the Subject. Add your own email as a
+   Key manager, and leave the metadata empty for now. Click **Save consumer**
+   once you're done.
+
+   <ModalScreenshot>
+
+   ![New Consumer](../../public/media/step-3-add-api-key-auth/image-3.png)
+
+   </ModalScreenshot>
+
+3. Copy your API Key
+
+   After your API Key consumer is created, copy your new API Key by clicking the
+   copy button (next to the eye icon).
+
+   ![Copy Key](../../public/media/step-3-add-api-key-auth/image-4.png)
+
+4. Test out your API Key
+
+   Navigate back to the **Route Designer**, and select your route. Next to the
+   path of your route, click the **Test** button and fire off a request.
+
+   <ModalScreenshot>
+
+   ![Failed unauthorized error](../../public/media/step-3-add-api-key-auth/test-policy.png)
+
+   </ModalScreenshot>
+
+   You should get a 401 Unauthorized response - as we'ven't supplied the API key
+   yet. Add an new `authorization` header with the value `Bearer <YOUR_API_KEY>`
+   and insert the API Key you got from the developer portal.
+
+   You should now get a 200 OK.
+
+   <ModalScreenshot>
+
+   ![successful response](../../public/media/step-3-add-api-key-auth/image-6.png)
+
+   </ModalScreenshot>
+
+   :::note
+
+   We also offer an API for our API key service that allows you to
+   programmatically create consumers and even create your own developer portal
+   or integrate key management into your existing dashboard. See
+   [this document for details](./api-key-api.md).
+
+   :::
+
+5. View your API Documentation
+
+   Whenever you deploy a new endpoint on Zuplo, it will automatically be added
+   to your
+   [autogenerated developer documentation portal](../dev-portal/introduction.md).
+
+   To access your API's developer portal, click the **Gateway deployed** button
+   in your toolbar and click the link under Developer Portal.
+   ![Developer portal menu](../../public/media/step-2-add-rate-limiting/image-5.png)
+
+   When you use certain policies like API keys, Zuplo will document properties
+   like headers associated with that policy. As you can see on the right, the
+   API key policy's `Authorization` header has been documented for you.
+
+   ![Developer Portal Endpoint](../../public/media/step-3-add-api-key-auth/image-7.png)
+
+   Additionally, a new Authentication section has been added to your developer
+   portal. Users of your API can sign in, view & manage their API keys, test
+   your endpoints, track API usage, and much more! You can learn more about that
+   in
+   [our developer portal auth docs](/docs/dev-portal/zudoku/configuration/authentication).
+
+</Stepper>
+
+**NEXT** Try
+[Step 4 - Connect Source Control and Deploy to the Edge](./step-4-deploying-to-the-edge.mdx).