API Management
Author: Ronald Fung
Creation Date: 23 May 2023
Next Modified Date: 23 May 2024
A. Introduction
To learn what API Management is and how it works, visit Microsoft’s Learning Channel.
APIs exist at the intersection of business, products, and technologies. They power customer experience, business relationships, and internal innovation.
Unlike the many choices that a technical leader must make regarding programming languages, libraries, and infrastructure, APIs have a direct impact on the speed of software delivery within a business. Therefore, leaders must not leave an organization’s API strategy up to their developers as they build new APIs. Instead, it requires a thoughtful and well-planned approach across the entire organization.
What are web APIs? As a review, an application programming interface (API) specifies how software components and systems should interact with each other. Web APIs extend this interaction beyond a single application by using HTTP, the language of the web, as the network protocol.
A web API doesn’t have to be RESTful. It doesn’t have to use SOAP. It doesn’t have to use JSON or XML or OAuth or be built in a specific programming language or framework. It doesn’t have to have pretty URLs. Web APIs may exhibit some, all, or none of these traits.
The only requirement for a web API is that it allows one program or software component to interact with another in a repeatable way over HTTP.
B. How is it used at Seagen
The process for using the APIM is simple. There are 4 types of access levels.
Public Products
Internal Products
Restricted Products
Secret Products
The process for setting them up is simple. When the new API is created or deployed via Terraform, that API is assigned to a Product. The product represents a Business Domain.
The Business domain is classified using the data classification types as noted above. There can also be Products based on sub-domain. For instance, we may have an HRIS business domain but a Person sub-domain.
Both would be classified as Secret following the standard.
After classifying the API, we determine the accessibility of the Product. The following rules have been configured again following the classification standards.
Public Products are open and available for anyone to use.
Internal Products require subscriptions at a minimum.
Restricted Products require subscriptions and an approval by the API owner or domain owner
Secret Products require invitation, subscriptions, and approval by the API owner or domain owner
When a developer or analyst would like to use an API, they follow these basic steps.
Visit the APIM Developer Portal
Authenticate/Sign Up using your AAD account
If public APIs will be used, subscribe to the Product where they appear, that will give you access to all the APIs in that product
If Internal or Restricted, subscribe to the Product, the API Owner, another Developer Lead, or domain owner will approve your access. Once approved, you can now use any API in that product.
If Secret, the API owner, Developer Lead or domain owner will send an invite from the APIM Portal which will alert you to the product and send you a link to subscribe. Once you subscribe, the inviter will approve your subscription request and you can use the APIM.
Standards and Practices
Here are some common rules when using using the APIM.
Never use the master OCP-APIM-Subscription-Key. That is for the portal and will compromise the system
Always expect the token you are using to expire
Never share your subscription token
When integrating with a solution or application, use an API service account or identity to act in your behalf, never use your own Seagen account to integrate
Follow the directions of the portal and don’t break the service by trying something illegal
It is a good practice to use Postman to connect to the APIM. That allows you to verify your access works
It is a good practices to publish all application APIs to the APIM and integrate through that tool rather than connecting a platform to an API
C. Features
Azure API Management has many use cases. Of primary importance is the ability to create an enterprise-grade service and deploy it once for everyone to use. The APIM is designed to be created at the organization level. That means only one instance of the APIm is necessary. This helps Seagen focus on the self-service model of not only deploying but also management.
Some common use cases are:
Internal developers getting access to enterprise services
Developers contributing back to domain services
Developers creating sub-domain enterprise services
External developers accessing common enterprise services
External developers or integration engineers accessing application level APIs
System Analysts testing interfaces
Solutions Architects designing new REST APIs
Enterprise Architects designing new enterprise solutions
Enterprise Application Developers publishing internal or external APIs
Monitoring support for ongoing operations
Bespoke application development
D. Where Implemented
E. How it is tested
There are several ways to test Azure API Management. Here are a few options:
Using the Azure Portal: You can test your APIs using the Test feature in the Azure Portal. Simply navigate to your API Management instance, select the API you want to test, and click on the Test tab. You can then enter sample requests and view the responses to ensure that your API is functioning correctly.
Using Postman: Postman is a popular tool for testing APIs. You can create collections of requests in Postman and use them to test your API endpoints. To test your Azure API Management instance, you will need to import your API definition into Postman and then create requests based on that definition.
Using Swagger UI: Swagger UI is an open-source tool that can be used to test APIs. You can import your API definition into Swagger UI and then use the interface to test your API endpoints. Swagger UI provides a visual representation of your API endpoints and allows you to easily test each endpoint.
Using automated testing tools: There are several automated testing tools available that can be used to test APIs, such as Selenium and Katalon. These tools allow you to create automated tests for your APIs, which can be run on a regular basis to ensure that your APIs are functioning correctly.
Overall, testing your Azure API Management instance is important to ensure that your APIs are functioning correctly and meeting your business requirements. By using one or more of the above methods, you can ensure that your APIs are tested thoroughly and consistently. AI-generated content may be incorrect
F. 2023 Roadmap
The following describes the plan for the APIM in 2023.
Centralize on one enterprise version of the APIM using developer-dev
Solidify and release portal styling
Fully integrate SSO for portal access
Permit 3rd parties to access key resources
Define what an enterprise API is
Deploy through automation all enterprise APIs
Assign APIs to products based on data classification and business domain/sub-domain
Release version 1.0 of this global service to the enterprise
Enhance the cognitive services with how-tos
Enhance Terraform deploy to include any service and self-service
Expose monitoring and usage dashboard
Align APIs, domains, and sub-domains to business products
Create JWT token request process
Release Notes
1.0 - Q1 2023 - Includes common framework and Terraform automation. Also includes Cognitive Services.
G. 2024 Roadmap
The following describes the plan for APIM in 2024.
Add all research APIs to portal
Add all enterprise system APIs to portal
Add all common utility APIs to portal
Extend current Standard version to Enterprise and add second location
H. Known Issues
Like any software product, Azure API Management may experience some issues. Here are some of the known issues that users have reported:
Performance issues: Users have reported slow API Management performance, particularly when managing large numbers of APIs or subscriptions. This can lead to delays in processing requests and may impact user experience.
Custom domains: Users have reported issues with setting up custom domains in Azure API Management. This can cause issues with SSL certificates and may impact API availability.
Authentication issues: Users have reported issues with authentication when using Azure API Management. This can cause issues with API access and may require manual intervention to resolve.
Metrics and logging: Users have reported issues with metrics and logging in Azure API Management. This can make it difficult to track usage and diagnose issues with APIs.
Versioning: Users have reported issues with API versioning in Azure API Management. This can make it difficult to manage multiple versions of APIs and may require manual intervention to resolve.
Microsoft is constantly working to address these issues and improve the functionality of Azure API Management. If you experience any issues with Azure API Management, it is recommended that you contact Microsoft support for assistance.
[x] Reviewed by Enterprise Architecture
[x] Reviewed by Application Development
[x] Reviewed by Data Architecture