alt text

API Creation via API Management (APIM)

Introduction

API Management (APIM) is a service in Azure that allows users to expose Application Programming Interfaces (APIs) behind a service that takes care of security, versioning, and analytics¹. It is a powerful tool that allows AI developers to control the way their network-based services are accessed. APIM is currently used for our coding assistants, chatbots, automations, and search capabilities. By following this guide, you will understand what capabilities APIM offers and how you can start using it. For more information, please consult the Microsoft Learn documentation section related to APIM.

Getting Started

To manage your APIs, you must first have access to the AI/ML APIM Azure resource. This permission can only be granted by a maintainer, so please email us first to request access for your developer team. Your AD group or user will be added to our Role-based Access Control (RBAC) list within the week. You should also be given access to our GitHub repository where we maintain API source code.

1. Create your REST API

We currently support REST APIs following an OpenAPI v3 YAML specification. Depending on which framework you've used to build your application, it may support exporting this spec. For example, FastAPI and Flask in Python or TypeScript (with tsoa) can be used to build OpenAPI-compatible backends. It is recommended that you work with an app framework that supports automatic OpenAPI export to minimize the number of manual procedures involved in deployment.

To build a spec of your own manually, open a text editor or IDE and create a file called <your-api-name>.yaml. If this is your first time writing an OpenAPI spec, we highly recommend starting from an example. The Microsoft Learn docs point to the Petstore OpenAPI YAML file (download here). In addition, there is a tutorial available on the OpenAPI site. Coding assistants are suggested to check your work and correct any mistakes.

The top of your document should appear similar to this:

openapi: 3.0.1                                      # Or whatever higher version, as long as it's >=3, <4
info:
  title: <API-Title>                                # A title that can be used to refer to your API
  description: "<description-of-your-api>"          # A long-ish description of what your API entails and what the goal of interaction is
  termsOfService: <optional>                        # If you abide by any sort of terms of service for providing this API
  contact:
    name: <your-name>
    email: <your-email>
    url: <optional-site-url>                        # Please put a CNH site only or a link to your group's GitHub
  version: '1.0'
servers:
  - url: https://<name-of-apim-instance>.azure-api.net/<your/endpoint>     # The name of the APIM instance and endpoint will be filled in by our team
paths:
  /<operation-path1>:                               # Ex. /responses, /records, /retrieve
    <http-method-type>:                             # Usually you will use GET/POST requests since we support REST APIs (e.g., get:, post:)
      summary: <short-description-of-operation>
      description: <longer-description>
      operationId: <unique-string-for-operation>    # Can be something like operationPath1 or getResponseId
      requestBody:
        <schema-for-request-info>                   # To set structures for requests and responses, use the components section at the bottom
      responses:
        <schema-for-expected-responses-info>
  '/<operation-path2>':                             # Repeat for as many operations as necessary
    <...same-as-above...>
components:
  schemas:
    <definition-for-object-schema-1>: ...
    <definition-for-object-schema-2>: ...
    ...

At the end of writing, you should validate your spec using a trusted validation program. DO NOT use one of the validators online. Instead, use a validator that runs locally on your own machine with the source available. For example, the OpenAPI Spec Validator uses a Python program that runs via the CLI for validation.

2. Add the API to APIM

Submit a Request Form

Link to request form

First, discuss your API features and capabilities with a member of the AI/ML Engineering team. You should be prepared to address:

An overview of API functionality
Who requires access to your API
Expected usage levels (low/medium/high, queries per minute/day, etc.)
How often you expect to update the API (minimum twice a year)
What alerts/logs you require and where they should be directed

After your presentation, the Engineering team will ask you for a copy of your OpenAPI specification. From here, you have two paths for maintenance:

GitOps

It is recommended that changes to your API be tracked through GitHub. A member of our team will provide access to a repo where you may submit changes to your API via pull request. Be sure you are familiar with our Git procedures prior to making changes. The general flow will be as follows:

Clone the repository to a local folder and make sure you are on the main branch (use git branch to check)
Start by using git branch <name-of-branch> to create a branch to hold your file changes
Use git switch <name-of-branch> to change to that branch
Make a series of API changes to the OpenAPI specification document in your team's folder under apis/
- Changes to any other files should be discussed with the AI engineering team
- If comfortable working with policies, operation-specific policies may be edited under apis/<api-name>/operations/<operation-name>/policy.xml
Check that the specification is a valid OpenAPI file
Use git add . && git commit -m "<brief-commit-msg>" to describe the changes made
Push the changes up to GitHub using git push
On the GitHub web page, click the "Pull Requests" tab and click "New pull request" button
Keep the base branch as main and select the branch you used for changes on the "compare" dropdown. Click the "Create pull request" button
Describe your changes and submit

From here, an APIM maintainer will review your proposed changes, provide feedback if necessary, and merge the changes into our main working branch once approved. An automation should update the APIM instance immediately, which means your API will be ready for use within a few minutes of approval.

Manual

An alternative to Git-based APIM management is to use manual file uploads. As APIM access is currently unavailable to teams outside of AI engineering, all changes should be submitted via email to AI_ML_Advanced_Analytics@childrensnational.org. Please provide the following in your email, which should have the subject heading [APIM] [\<Team-Name>] [\<API-Name>]:

An updated OpenAPI specification YAML file with a version number
A description of what has changed
How soon it needs to be implemented

We cannot guarantee that your API changes will go through immediately. However, providing as much detail as possible will help speed up the process.

3. Manage access to the API

Prior to the publication of your API, you must make a determination of who is allowed to access specific endpoints on it. There are generally two main avenues for providing access: API keys and OAuth applications.

OAuth2 Apps (recommended)

APIs should use Microsoft Entra ID and OAuth 2.0+ for authentication whenever possible. OAuth is preferred over shared API keys because it supports the granting of individual permissions, is more secure than keeping passwords in plaintext, and provides information on users of the API.

This setup normally includes creating 3 Azure resources:

An API app registration, which represents the API and defines its exposed scopes or application roles
A client app registration, which represents the service calling the API and is granted the necessary permissions. This controls access to the app in the form of login/single sign-on (SSO)
An enterprise application/service principal, which is used to manage access through Active Directory groups or users

Microsoft Entra ID provides a token containing information about the user in the form of a JSON Web Token (JWT) after reaching out to the client app registration. APIM validates this token before forwarding the request to the backend API app registration according to the policy set in the <validate-jwt> policy block of an API operation. This is also where user information can be collected according to a custom policy definition.

To request this configuration, provide us with a few details of how your workflow operates and how users should be reaching the application. OAuth may not always be the solution, especially for automated-workflows with no user interaction.

API Keys

Caution

If you intend to secure your API using API keys, ensure that the value remains protected within your user group. We do not condone sharing this value via SharePoint files, sticky notes, or mass email. Share only with trusted individuals who understand the risk of plaintext passwords like API keys.

Key-based access to APIs is discouraged except in situations that warrant usage, such as automated workflows. If necessary, you can create a key scoped to your API by following the pattern used by other APIs in the subscriptions folder.

To create a new key, add a subfolder under subscriptions named for the access this key will grant. If it is scoped only to your API, the subfolder should share its name with the API. The subfolder should contain a single file called subscriptionInformation.json. The contents of the file should be as follows:

{
  "properties": {
    "displayName": "<Name for your API Key>",
    "scope": "/apis/<name-of-your-api>",
    "allowTracing": false,
    "state": "active"
  }
}

Once this change passes review by the APIM maintainers and your request for an API key is approved, you will receive a message containing your key in plaintext. Copy the value for yourself and keep it safe. This value should be rotated every six months at a minimum.

4. Version your API

The current version of the API in APIM is referred to as a revision. At a given time, only one revision shall be active for a given API. Other revisions shall be maintained by APIM only for testing purposes. To access a specific revision, add ;rev={revisionNumber} to the end of the API endpoint (e.g. /<api-name>/<operation-name>;rev=1) in a query. API revisions should be rotated out of APIM when they are no longer used.

API versions are maintained in source control via GitHub. This means a given API version may interface with different revisions of the deployed APIs. For this reason, API versions are referred to using our v<Major>.<Minor>.<Patch> naming scheme while revisions use increasing natural numbers (e.g. 1, 2, 3). If you are using GitOps to maintain your API, check the apiInformation.json file in the apis/<your-api-name> folder to see the revision number. If you are maintaining your API manually, please reach out to an APIM maintainer to ask for a revision number or else leave the revision tag off the query to use the most recent one.

5. Test the API

Running a test of your API is simplest through the APIM Azure Portal interface. The dedicated "Test" menu on each API operation allows sending a query to the specified backend API with built-in APIM processing. Query and header parameters should match their usage in production, but will be verified in the DevTest instance of APIM first.

In the absence of Azure Portal access, tests should be conducted using revisions (see Version your API) following the deployment of an API to the DevTest instance. The revision number should be available following deployment of the API in GitHub or will be provided by the APIM maintainers. Make test queries to API and ensure that all operations are working before requesting promotion to production. Unit and integration testing is an encouraged practice. The AI/ML engineering team can assist by providing DevTest logs, but cannot help debug operations as they may involve backends that are outside of the team's control.

MCP Servers

We currently do not support remote Model Context Protocol (MCP) servers. If you have an MCP server that you would like to host within our Azure tenant, please reach out to a member of the AI/ML engineering team. Converting an API exposed via APIM into a remote MCP server is being explored.

Monitoring

Use Application Insights on instances of APIM to automatically provide logging over API operations. From App Insights, you can obtain:

Request timings
Caller IDs and emails
Payload sizes
LLM token metrics

References

Note that APIM does not provide cloud hosting for applications. That must be procured separately and provide a means of access. Please email the AI/ML team if you require cloud hosting options and we can discuss paths forward. ↩