azure/apim-lab

API Management - Hands-on Lab Workshop

About this workshop

This hands-on lab will guide you through the different concepts around Azure API Management, from the creation to the DevOps, including good practices in terms of versioning, security, and so on. It is designed to bring customers and partners to a 200-level understanding of Azure Api Management. This is meant to be a hands-on lab experience, all instructions are provided, but a basic level of understanding of apis is expected(http operations, networking basics, openapi, rest, soap, oauth2, and other concepts).

This workshop is delivered using Github Pages and Just-The-Docs theme at https://azure.github.io/apim-lab/

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

apim-lab's Issues

Policy expression "abort policy" sample should reflect the output shown in the image

This is just a request for consistency of the sample ran to what the output will appear as in the Lab image. message

Creating an API from OpenAPI specification results in false "duplicate signature" error.

Describe the bug
When importing the following OpenApi spec with the OpenApi importer in Azure Api Management, an error is returned:

'Importing API has duplicate signature operations: 2 operations with signature 'GET /api/group-users/{id}'

To Reproduce
Steps to reproduce the behavior:

1. Go to Azure Api Management in portal.azure.com
2. Click on Apis
3. Click on Add Api
4. Click on Create definition from OpenAPI
5. Use the following OpenApi spec:

{
    "x-generator": "NSwag v14.0.2.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))",
    "openapi": "3.0.0",
    "info": {
      "title": "Test web API",
      "description": "Test web API",
      "version": "1.0.0"
    },
    "servers": [
      {
        "url": "https://testwebapi.com"
      }
    ],
    "paths": {
      "/api/group-users/{id}": {
        "get": {
          "tags": [
            "GroupUsers"
          ],
          "operationId": "GroupUsers_GetById",
          "parameters": [
            {
              "name": "id",
              "in": "path",
              "required": true,
              "schema": {
                "type": "integer",
                "format": "int32"
              },
              "x-position": 1
            }
          ],
          "responses": {
            "200": {
              "description": "",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/groupUser"
                  }
                }
              }
            },
          }
          }
        },
      "/api/group-users/{guidId}": {
        "get": {
          "tags": [
            "GroupUsers"
          ],
          "operationId": "GroupUsers_GetByguidId",
          "parameters": [
            {
              "name": "guidId",
              "in": "path",
              "required": true,
              "schema": {
                "type": "string",
                "format": "guid"
              },
              "x-position": 1
            }
          ],
            "responses": {
            "200": {
              "description": "",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/groupUser"
                  }
                }
              }
            }
          }
          }
        }
      },
    "components": {
      "schemas": {
            "groupUser": {
              "readOnly": true,
              "nullable": true,
              "oneOf": [
                {
                  "$ref": "#/components/schemas/GroupUser"
                }
              ]
            },"GroupUser": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "integer",
              "readOnly": true,
              "format": "int32"
            }
          }
        },
          }
      }
  }

Expected behavior
I expect the Import to succeed. There isn't a duplicate endpoint. While the definition is the same, it differs in datatype and OperationId. This is a valid open API spec.

Screenshots

Add the architecture design session challenge

Implementing new just-the-docs theme

• right order for left menu
• adding contributor sections to the home page
• adding better description to the home page
• removing has child of pages that do not have childs
• changing theme default colors
• adding darkmode switch

Add custom Just the Docs styling & Revise Markdown

• Just the Docs does not entirely implement Markdown's typical styling (e.g. blockquotes).

• Our screenshots are fuzzy because they are taken on a larger resolution, but our Just the Docs styling is currently limiting width to 712px.

https://pmarsceill.github.io/just-the-docs/docs/customization/

Typo and Suggestion in Developer Portal -> Publishing Developer Portal

The first sentence in the second paragraph reads:

Once you have accessed the dev portal in admin mode. Now, we can proceed with its publishing for anonymous and authenticaded roles.

Suggested change:

After having accessed the dev portal in admin mode, you can now proceed with publishing to allow for anonymous and authenticated roles.

spelling error "and"

https://azure.github.io/apim-lab/apim-lab/6-analyticsMonitoring/apimanagement-6-3-EventHub.html

Add the Mock Response in Text Form

The mock-response policy is only shown in a screenshot in the Mock policy lab. It would be helpful to also add it in a code snippet like we do for almost all, if not all, other examples.

provide clarification between azure subscription and azure api management subscriptions

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

low code - no code challenge

Clarify APIM Creation

Valuable feedback from a customer workshop was that we needed to be clearer on our API Management instance request:

• We should emphasize that no other settings other than the ones we ask for are set as deviation from that can cause problems post-setup. We should explain that clearly to provide reason for this emphasis.

• We should also ask to invoke the Echo API afterwards to ensure APIM was set up properly.

log to eventhub challenge

Typo in Adding APIs -> Calling APIs

Documentation reads:

Here we will se this form, where we can add the domain name of our frontend

Should read:

Here we will see this form, where we can add the domain name of our frontend

Update DevOps section to include GitHub

We presently only provide guidance for ADO, but as GitHub is our strategic solution, we need to focus on its integration with APIM as well.

Fix Event Hub Namespace & Update Documentation

The Logging with Event Hub lab has some discrepancies with respect to the Event Hub namespace that need to be fixed to avoid confusion.

Log-to-eventhub section would be clearer with addition of one step

Describe the bug
at: https://azure.github.io/apim-lab/apim-lab/6-analyticsMonitoring/apimanagement-6-3-EventHub.html#configure-log-to-eventhub-policies
Between step 5 and 6 it would be clearer if there was another step to open policy code editor

To Reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Additional context
Add any other context about the problem here.

Add text or red boxes to highlight that "Both" and http(s) for backend is needed for API import Cal API.

When adding the Calculator API and on use if in settings "both" and Url is not set to http(s) it will come back to an HTTP 500 error. While this will likely be passed over by those knowledgeable to the service it may cause a blocker to those not familiar with the setting as it is an HTTP call. Also, if you it can be specified why this is needed to not arrive at the HTTP 500 would be great.

Define contribution guide

developer portal instrucstions, wrong verb in image and instructions

https://azure.github.io/apim-lab/apim-lab/2-developerPortal/apimanagement-2-1.html

Add Self Hosted Gateway doc

Add Policy Fragments

Policy fragments were just released and provide the means to avoid redundant code. This is very useful for customers and could be added towards the end of the Policies section.

Workspaces changes the way to test APIs with a subscription key

Describe the bug
After creating a new APIM instance and testing the Echo API, subscription keys cannot be fetched automatically now.

To Reproduce
Steps to reproduce the behavior:

1. Deploy new API Management instance
2. Go to 'APIs'
3. Click on 'Echo API'
4. Click on 'Test' tab
5. See error

Expected behavior
We should be able to document how to easily test the Echo API.

Screenshots

add new instructions for activating developer portal

now you have to open the admin experience before publishing the portal

Fuzzy Images in Auth Code Flow

Is your feature request related to a problem? Please describe.
The images on the auth code flow have an arrow on the right hand side that doesn't seem like it should be there. Additionally, some of the images contain very small text that is hard to read (small img 1 | small img 2 | small img 3 | small img 4 ).

Describe the solution you'd like
Making these images readable or with alt text would be nice.

Describe alternatives you've considered
N/A

Additional context
N/A

Add more detail on why (context.User.Id) is not getting evaluated from Azure management portal under Transformation policies

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Add new colours api and frontend

Describe the bug
Colors api and frontend url have changed, need to update lab accordingly.

Append self hosted gateway caching dapr policy

Deploy to Azure Button No Longer Visible

Describe the bug
The Deploy to Azure button to create the APIM instance is no longer visible.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://azure.github.io/apim-lab/apim-lab/1-apimCreation.
2. Note the missing button.

Expected behavior
The Deploy to Azure button should show.

Additional context
The cert on azuredeploy.net expired on 1/13/22.

We should be sourcing the button from the proper location.

Use Webhook.site

We presently use Microsoft Teams as a target for the webhook in the Send One-Way Request policy example. Using Teams requires a bit of overhead and may also not work well for every user due to necessary rights on the Teams channel.

Using Webhook.site provides a much simpler way to demonstrate the one-way policy. The payload we are sending is benign, and the APIM instance is experimental for the lab, meaning there isn't a concern about the payload being sent.

Emphasize Test Tab is Stateless

When testing APIM, users often set headers, select products, etc. on the Test tab, then switch away to do something else after the test. When coming back to the Test tab, there is an expectation that the test parameters were retained, when, in fact, they are stateless and need to be repopulated. This is a less than ideal situation, and we do not make it very clear in our lab documentation that parameters need to be repopulated.

Look through the parts of the labs where tests are initiated from the APIM Azure Portal and consider refining the language to emphasize the need to repopulate.

oauth2 - authorization flow challenge

Abort Processing Policy Example Lists Wrong HTTP Code

The Abort processing policy states that a 599 is returned when, in fact, a 500 is listed in the policy code snippet. Fix the policy to return a 500.

link giving 404 error

In Prerequisites nindex.md the links for deploying your own API is giving 404 error

apim-lab/0-labPrerequisites/index.md

To Reproduce
Steps to reproduce the behavior:

1. Go to 'apim-lab/0-labPrerequisites/index.md'
2. Scroll down to 'in case this website is down you can deploy your own API using the following instructions'
3. Click on 'instructions'
4. See error

Update the Security - JWT Lab

Update screenshots, review and organize content.

when using dark mode , white flash appears

This is related to an implementation of browser level dark-light mode, expecting a new version of just the docs might fix this just-the-docs/just-the-docs#560

Add Azure Function API

Fix Formatting on Add API From Scratch

The formatting needs to be fixed on the Add API From Scratch lab.

1. GetPeople - Display name: GetPeople - Name: getpeople - URL: GET /people/ 2) GetPeopleById - Display name: GetPeopleById - Name: getpeoplebyid - URL: GET /people/{id}/

improve instructions in colors web config

Instructions are not great. Try this:

go to the site Color Home - ColorWeb (markcolorweb.azurewebsites.net)
Click on the hamburger menu > config
Set the API URL to your APIM url which contains the key. for example:

https://rt-lab-apims.azure-api.net/color/api/RandomColor?key=11a8eca6657f4427b9d1d01a2f9642a5
Click Submit
Then on the next page click start

Fix broken links

We have some broken links, particularly on the (Logging with Event Hub)[https://azure.github.io/apim-lab/apim-lab/6-analyticsMonitoring/apimanagement-6-3-EventHub.html] page.

Verify all links and fix them.

Implementing github codespaces for inner-loop using github pages, ruby

• create basic devcontainer files
• add just the docs requirements
• add extensions
• add additional utilities

devops challenge - github actions and apimdevopskit

Calculator API CORS Issue in Developer Portal Due to Incorrect Protocol for APIM

Describe the bug

The screenshot in the documentation on importing the Calculator API shows to set the URL scheme to HTTP. While testing from within APIM itself works and returns a proper 200, using the Developer Portal fails with a CORS issue. Specifically, it's failing due to a mixed-content violation. The Developer Portal itself runs on HTTPS and is attempting to make a call to APIM but fails due to APIM only accepting HTTP.

To Reproduce
Steps to reproduce the behavior:

1. Set up the Calculator API as described here.
2. Go to the Developer Portal and try to make a request to the Calculator API.
3. Note the CORS error in the response.
4. Open the brower's developer tools and observe the mixed-content error on the network tab.

Expected behavior
The request should be allowed, and a 200 should be returned along with a response body showing the result.

Policy Expressions->Transformational Policies->Amend what’s passed to the backend - Tracing location incorrect

Policy Expressions->Transformational Policies->Amend what’s passed to the backend

This section mentions viewing the Trace in the developer portal, I saw this note:

"Note - this trace below was from the Developer portal. I got errors when testing from the Azure Management portal, as the [User Id] is unable to be evaluated."

I then spent some time trying to find out how to view the Trace in the developer portal and then had to ask for help. I think viewing tracing in the developer portal was mentioned in an earlier exercise too. I asked for help and it was explained that basically you can't with a regular user. Could the content be updated to show how to view the trace correctly in this exercise.

Add cleanup step after "Abort processing policy" Cal API throwing HTTP500 later in the Lab

Policy Expressions | Abort processing policy | http 500 condition

As the Cal API is used at later place within the Lab this condition will cause an HTTP 500 when it is in a working state. Can you apply a cleanup step at the end of this section?

The request has both SAS authentication scheme and 'Bearer' authorization scheme. Only one scheme should be used.

Describe the bug

After following JSON Web Token Validation at
https://azure.github.io/apim-lab/apim-lab/7-security/apimanagement-7-1-JWT-Validation.html
I get this response:

The request has both SAS authentication scheme and 'Bearer' authorization scheme. Only one scheme should be used

To Reproduce
Steps to reproduce the behavior:
Follow the above lab excersize: Azure Apim Hands On Lab

Expected behavior
Http Status code 200 returned but im getting the 401

Add admin consent permissions needed for Authorization Code Flow to the Prereq page

In the steps for Authorization Code Flow admin consent is needed to set SP permissions. Can you please include this to the Prerequisites page?

Add APIM infrastructure DevOps story (Terraform?)

Add Test Request Instructions to Application Insights Lab

The Application Insights lab does not presently point out to generate API requests after AI has been set up. Rather, we mention analyzing requests right away, which we should not have any yet in our test instance.

Running Mark's Color Website can generate hundreds of requests in seconds, which is a great way to put load onto APIM and results into AI.

Set Hyperlinks to Open In New Tab/Window

Most, if not all, of the hyperlinks presently replace the current tab/window when executed. As we want to remain on the workshop page, we should open hyperlinks in new tabs/windows.

Certificate validation challenge