Radimaging Ltd - Paul Beck's Technical Working Notes for Microsoft Technology: APIM

APIM debugging, tracing, monitoring tricks and tips

Documenting you API in the Developer portal (this post)

Friday 12 February 2021

APIM debugging, tracing, monitoring tricks and tips

Debugging APIM requests from Visual Studio code

Has an extension for debugging APIM.

Azure API Management - Visual Studio Marketplace

It's also useful to have a APIM requesting/client extension installed

Tracing APIM

To get a full trace add the HTTP header "Ocp-Apim-Trace: true" to the request and the response shall contain a URL to retrieve the trace information.

App Insights for APIM

Logs in three places:

Incoming requests (come into APIM)
Dependency request (go to backend/outgoing)
if an exception occurs it is also logged in App Insights

So logging can be set at either the global or API level.

Setup in APIM > Monitoring > Application Insights (link APIM to the App insights Logger).

Documentation Tips

Ensure you fill in relevant descriptions and summaries. It's also key to provide examples.

https://swagger.io/docs/specification/adding-examples/

My Technical Working Notes for Microsoft Technology: APIM OpenAPI Specification Documentation Example within the Developer Portal (pbeck.co.uk)

APIM documentation updates on the Developer portal (after re-publishing). It has a great UI, but ensure the summaries are added for param/attributes to get a truly rich integration set of documentation (it will save so many questions and time). I also like to add a getting started guide, keep it short and simple and most importantly have a simple explanation of security/authentication and connectivity.

- in: query

name: age

schema:

type: integer

maximum: 3

examples: # Multiple examples

max: # Distinct name

value: 3 # Example value

summary: The age is dependent on dob, min is 0, can't be negative

PB APIM Series:

APIM Testing with Postman (this post)

Developer Portal - Example documenting your API within YAML

APIM debugging, tracing, monitoring tricks and tips (this post)

Monday 19 October 2020

APIM High Availability and Performance across Regions

Overview: APIM can be setup in multiple regions and incoming request will be routed to the closest APIM endpoint. If there is only 1 APIM region, it is best to ensure the API/App Service/Function is hosted in the same region. With multiple APIM's you can also host a API in the same region. The routing is either done automatically using Azure Front Door or via policy on the APIM.

Front Door can be substituted with Azure WAF, or Cloudflare or Barracuda's SaaS solution.

https://www.pbeck.co.uk/2020/10/waf-options.html

More Info:

https://docs.microsoft.com/en-us/azure/api-management/api-management-howto-deploy-multi-region

Tuesday 29 September 2020

Secure APIM using AAD B2C

Overview: I have never connected AAD B2C to APIM myself, other on my project teams havde done it so I went thru it and it was super easy.

Followed the instructions:

https://docs.microsoft.com/en-us/azure/active-directory-b2c/secure-api-management?tabs=applications-legacy

Postman to validate:

PB APIM Series:

Developer Portal - Example documenting your API within YAML

Sunday 13 September 2020

Options Layering API's on Data Sources - Micrososervices kind of

Hasura takes data sources such as SQL, Postgress & MySQL and converts it into GraphQL API's. SQL Server is in preview. Service is available on Azure and hooks into AAD and AAD B2C. Hasuru looks extremely interesting and useful. Potentially a great time saver.

CDS/DataFelx/Oakdale - Allows for Entity creation and provides REST API's.

SharePoint lists provide HTTP API's for CRUD operations.

REST API's vs GraphQL

OpenAPI specification (previously known as the Swagger specification) is my default for an API, this allows for a known RESTful API that anyone with access can use. Open API has set contracts that returned defined objects which is great, you can work with the API like a database with simple CRUD operations as defined by the specification. The issue is that the returned objects are fixed in structure so you may need 2 or more queries to get the data you are looking for. Alternatively, GrapghQL allows the developer to ask for the data exactly as the want it.

Open API example:

/api/user/{2} returns the user object // Get the user object for user 2

/api/users/{2}/orders/10 // Returns the last 10 orders for the user

GraphQL example:

Post a single HTTP request.

query {

User(id: "") {

name

orders(last: 10 {

orderid

totalamount

datemodified

}

Database Option Notes:

PostgreSQL - Hybrid relation database (Communitity edition free, standard and enterprise higher loads) sits on Linex but can also use Windows OS. Replicas are used for additional read-only nodes (I think up to 5 geo relicas allowed)

Can be hosted on Azure or AWS IaaS. PostgreSQL is also offered as a fully managed service (PaaS) on Azure (either single server or hyperscale).

MariaDB community fork off MySQL - Open source relation database used in the LAMP app stack. Azure MySQL manage service can have up to 5 replicas for read heavy workloads.

Wednesday 24 June 2020

Postman API Builder Intro

Overview: Tools for building and mocking API's. Swagger has good tooling and my original preferred choice. APIM - Great tooling, part of Azure and easy to replace mocks as you go along with the live implementation. Postman is offering a great set of functionality to rival Swagger and APIM. This post looks at Postman's new functionality around building API's.

Postman API Builder:
Not only a test rig, it now offers the ability to build API's and mock:

Mock - so you can test supports key and OAuth authentication
Assert Tests - You can specify asserts in postman

Test suite - generate collections/Collection Runner - Allows a set of related tests to run sequentially.

]

Document the API
Monitor
Version control for changes e.g. GITHub
API Versions supported
Note: Free plan has all of this, limited on the number of API's but all the features are on the free plan. The main notation formats are support including: Open API specification (OAS) & GraphQL

Summary:
I like Swagger tooling, I have done a few projects find APIM fantastic for building API's quickly. Postman historically was merely my test rig but looking at the functionality, Postman API Builder is a great option for designing and building API's. Postman is a good tool for building into CI/CD pipelines to validate API's.

Few more assert examples:

Postman offers a service to monitor API's using your postman collections, these can be triggered using Curl so can build into DevOps, Power Automated scheduled flows,....

sentry.io looks good as an alternative option

PB APIM Series:

APIM Testing with Postman (this post)

APIM debugging, tracing, monitoring tricks and tips

Developer Portal - Example documenting your API within YAML

More Examples:

Retrieving JSON values

Sunday 15 March 2020

Micro services Pattern without Microsoft Gateway for on-prem. data

PB APIM Series:

Wednesday 12 February 2020

Power Apps - DTAP Azure diagram

Overview: A sample architecture for DTAP in a highly controlled environment. There are a lot of variations and the ability to use Power Apps publishing.

There are a few ways to manage environment deployments.

Simple: Create in unmanaged solutions and Export and Deploy Managed solutions manually using the Power Platform Ux.
Enterprise: Build Azure DevOps pipelines to add unpacked code to Github and deploy solutions using Azure pipelines.
3rd party ALM tooling, some is specific to Dynamics.
Nov 2022 - Microsoft announce Power Platform Pipelines

Custom Connectors: As you step thru the DTAP environments using ALM to deploy you need to point the custom connector to the appropriate APIM (API):

Environment Variables are extremely useful for ALM

Tuesday 14 January 2020

API Management Advanced Mocking

My earlier post shows an Azure APIM engineer the steps to setup API Management Mocking

This post contains 2 screen shows showing how to add multiple mock responses to a request in APIM:

Amend the Get Operation Inbound Response Policy

Two APIM REST Requests showing dynamic mocking

Simple OpenAPI YAML 3 Example with Mock up examples for APIM.

To review:

Open an existing APIM Instance
Import the YAML file example (download and rename), thi sis a YAML 3.01 specification.

3. Add "Mock Response policy to all Incoming requests, alternatively you can do it at an operation level.

4. Test & Verify

Simple Example to mimic a 500 error for testing my API's

PB APIM Series:

APIM Mocking part 2 (This post)

APIM debugging, tracing, monitoring tricks and tips

Developer Portal - Example documenting your API within YAML

Sunday 12 January 2020

API Management Mocking

Problem: Create an Open API Specification (OAS) endpoint for testing using APIM

Background:

Azure has a great service to bring multiple API's under a single publishable layer (think MuleSoft). I like to use APIM to setup an initial contract that developers can use before setting up the actual API. This allows both the consumer teams and the back-end development team to work independently to this OpenAPI agreed contract.
Swagger originally owned and ended up creating the OpenAPI specification (OAS) that now of companies now use.
Swagger has great tooling for creating OAS API's, documentation, stub hosting and generating code such as .NET core that you can import into your dev environment.
Azure has a developer APIM instance licence that is relatively inexpensive (creating an APIM instance takes up to 20 minutes) but leaving it running for my personal dev is pretty expensive.

Overview: This post outlines the steps to setup an APIM instance using an OpenAPI file created in swagger. The APIM service shall be setup to return mock data.

Steps:

1. Create a new instance of APIM - Do this first as it takes up to 20 minutes before the service is ready.

1. Create an APIM instance

2. Open swagger.io in a browser and signup, "Create New", this gives you your starting OAS file for your custom API.

2. Login to Swagger and create the Open API file using YAML

3. Using the Swagger Editor, create the desired endpoints. It took me a few hours to get use to YAML as it is space sensitive but very readable.

3. Swagger editor

4. On the top right of the Swagger editor is the "Export" option. Click Export > Download API > JSON Unresolved. And keep the .json file ready to import into your APIM service.

5. Open APIM, and add a new API. APIs > Add API > Open API as show below.

Import OAS file into APIM

6. Import the file and the fields get populated per you instructions.

Upload the OpenAPI json file into APIM

7. The list of operations shows up - in my case i only have a single GET operation call \Get Customers

APIM Service is now created but not connected to a back-end

Mocking Info

8. Add Mocking to the end point. Highlight the Operation i.e. \Get List all Customers > Inbound Processing (Add Policy) button. Select "Mock-responses" > Save

9. Generate the JSON responses:

a) Select the Operation i.e. \GET List all customers

b) Frontend drop down > Form-based editor

c) Click the "Responses" tab

d) Click the "200 OK" link

e) Click in the Sample Box, and "Auto Generate", Save

The APIM service is now setup and we are ready to test.

1. Test using APIM's Testing tool

Check the 200 Response

Mocked response from APIM test tool

2. Testing using Postman

Open Postman, and craft the request as shown below:

Postman APIM testing

Note: There are several competitor products like Mulesoft, Amazon API gateway, Postman and Swagger also offer a lot of these features. There are other products that I have not used such as Kong API Gateway, GCP has Apigee, Gartner has a list of competitors and the magic quadrant done each year.

Summary: It is pretty straight forward to setup APIM mocking as shown above. And then easy to test it using Azure APIM tests and Postman. This post show how to add various mocked APIM responses.

PB APIM Series:

APIM Mocking (This post)

APIM debugging, tracing, monitoring tricks and tips

APIM Notes

5 Pricing Versions of APIM:

Developer Version (No SLA) - No prod data but has all the premium features.
Consumption Model (99.95% SLA) - priced per request serviced. Missing Dev portal, not a static IP adr - automatically scales,
Basic (99.95% SLA) - No AAD integration - Scales to 2 units
Standard (99.95% SLA) - Scales to 4 units
Premium (99.99% SLA) - Allows Custom Domains - unlimited scale. Also allows a single APIM instance to be scaled to more than 1 Azure Region. Also direct VNET access is only available in premium.

One can move (scale up or down) between Azure APIM pricing tiers but it take up to 45 minutes.

All consumption pricing tiers require the owner to setup or perform scaling.

APIM has Metrics to determine if the number of APIM units should be increased or decreased. The best metric is the capacity metric made up of Note: Ignore short spikes look for an average over 15 minutes. Microsoft suggests that the APIM Capacity metric running over 60% to 70% for a period of 30 minutes would indicate that scaling is appropriate.

When building your scaling strategy understand that adding APIM Units takes time (roughly 30 min) so scaling at 60% may not work for flash traffic in which case you'll need to account for this outside of only using metrics for scaling.

Tip: Regionally deployed APIM instances point to a single back-end URL, so it is best to keep the traffic routed to APIM in the same region as the back-end for simple scenarios, use the other region for failures and obviously you can multi-route back end traffic using Front Door for larger deployments.

Tip: Use Azure Key Vault for secrets.

Developer Portal - part of APIM, this portal/website is highly "customisable" and allows users to discover/consume our API's. User can check their access (only see API's they have access to) and to try/test the API.

Tips:

Users > Groups > Products > API EndPoints
Subscriptions assigned to 1) products or/and 2)API endpoints.
Transition policies great for turning SOAP into JSON. There are a lot of OOTB policies, easy to create policies using C#.
APIM Extension for VS Code is nice for working with APIM.

More Info:

https://www.youtube.com/watch?v=0yf_xm5cPIo
https://www.youtube.com/watch?v=gA2yxwKo0M0

PB APIM Series: