Azure Management API: Hướng Dẫn Tạo API Từ OpenAPI Specification - Part 1.1

Part 1: https://nhatkyhoctap.blogspot.com/2024/11/azure-management-api-huong-dan-tao-api.html

Trong phần này, mình cập nhật lại OpenAPI version 3 so với Part 1

Xem bài viết ở đây để biết được sự khác nhau của OpenAPI version 3 và 2: https://blog.stoplight.io/difference-between-open-v2-v3-v31

API PetStore

URL OpenAPI: https://petstore3.swagger.io/api/v3/openapi.json
Các endpoint nổi bật:

• GET /pet/{petId}: Truy vấn thông tin một thú cưng.
• POST /store/order: Đặt hàng cho thú cưng.
• GET /user/{username}: Lấy thông tin một người dùng.

Bạn có thể test thử API tại đây: https://petstore3.swagger.io/

Tạo API Mới trong Azure API Management

Trong Azure Portal, tìm kiếm và vào API Management Service của bạn. Trong tab APIs, chọn + Add API.
Chọn OpenAPI Specification trong danh sách các tùy chọn.

Ở mục OpenAPI specification, nhập URL

https://petstore3.swagger.io/api/v3/openapi.json

Điền thông tin API: 

• Display name: PetStore API.
• API URL suffix: petstore. 
• Tags: tổ chức APIs theo cách dễ dàng quản lý và tìm kiếm hơn.
• Products: nhóm các API để quản lý quyền truy cập và cung cấp các gói subscription cho developers.
  To publish the API, you must associate it with a product
  

Tính năng của Tags

• Nhóm API: Tổ chức các API theo chủ đề hoặc danh mục (ví dụ: pets, orders, users).
• Tìm kiếm dễ dàng hơn: Trong developer portal hoặc Azure API Management, bạn có thể sử dụng tags để lọc và tìm kiếm API.
• Gợi ý tổ chức API
• Sử dụng tags dựa trên chức năng API (ví dụ: CRUD, Order Management).
• Hoặc dựa trên team develop API (ví dụ: Finance, Logistics).

Tính năng của Products

• Quản lý API theo gói: Kết hợp nhiều API thành một product và cung cấp gói này cho developers.
• Subscription: Developers cần đăng ký để sử dụng API, có thể cấu hình gói miễn phí hoặc trả phí.
• Hạn chế quyền truy cập: Sử dụng Products để quản lý cấp phép, giới hạn số lượng request, hoặc kiểm soát bảo mật.

Ở section Subscription, bạn uncheck Subscription required

Bấm Create để hoàn tất.

Sau đó, bạn nhớ note lại Base URL, ex: https://nhatkyhoctap.azure-api.net/petstore

Testing new deployed API

Đây là một phần rất quan trọng. Bạn cần đảm bảo config đúng để liên kết APIM với backend, trước khi thực hiện các bước tiếp theo

Bạn có thể tham khảo API json hoặc Swagger UI trước khi thực hiện request:

1. HTTP Headers
2. HTTP Methods (GET, POSt, PUT, DELETE)
3. Request body/payload
4. HTTP Status (2xx, 3xx, 4xx, 5xx)
5. Base URL, resource path
6. URI/URL/Template Parameter
7. Query Parameter

API json (sử dụng Firefox để hiển thị JSON)

https://petstore3.swagger.io/api/v3/openapi.json

Ví dụ với API findByStatus, status sẽ chấp nhận string với 3 giá trị: available, pending, sold.
URL: /pet/findByStatus

"/pet/findByStatus": {
  "get": {
	"tags": [
	  "pet"
	],
	"summary": "Finds Pets by status",
	"description": "Multiple status values can be provided with comma separated strings",
	"operationId": "findPetsByStatus",
	"parameters": [
	  {
		"name": "status",
		"in": "query",
		"description": "Status values that need to be considered for filter",
		"required": false,
		"explode": true,
		"schema": {
		  "type": "string",
		  "default": "available",
		  "enum": [
			"available",
			"pending",
			"sold"
		  ]
		}
	  }
	],
	"responses": {
	  "200": {
		"description": "successful operation",
		"content": {
		  "application/xml": {
			"schema": {
			  "type": "array",
			  "items": {
				"$ref": "#/components/schemas/Pet"
			  }
			}
		  },
		  "application/json": {
			"schema": {
			  "type": "array",
			  "items": {
				"$ref": "#/components/schemas/Pet"
			  }
			}
		  }
		}
	  },
	  "400": {
		"description": "Invalid status value"
	  }
	},
	"security": [
	  {
		"petstore_auth": [
		  "write:pets",
		  "read:pets"
		]
	  }
	]
  }
}  

Swagger UI

https://petstore3.swagger.io/

Giả sử gọi API findByStatus

https://nhatkyhoctap.azure-api.net/petstore/pet/findByStatus?status=sold

Kết quả

[{
    "id": 5,
    "category": {
        "id": 1,
        "name": "Dogs"
    },
    "name": "Dog 2",
    "photoUrls": ["url1", "url2"],
    "tags": [{
        "id": 1,
        "name": "tag2"
    }, {
        "id": 2,
        "name": "tag3"
    }],
    "status": "sold"
}, {
    "id": 6,
    "name": "Special_char_owner_!@#$^&()`.testing",
    "photoUrls": ["https://petstore3.swagger.io/resources/photos/623389095.jpg"],
    "tags": [],
    "status": "sold"
}, {
    "id": 134674,
    "name": "見響见响仮仏!$%&()*+,-ƄƅƆḞḟṀʶʷʸ㥹",
    "photoUrls": ["https://petstore3.swagger.io/resources/photos/623389095.jpg"],
    "tags": [],
    "status": "sold"
}, {
    "id": 567,
    "category": {
        "id": 3916
    },
    "name": "AaeqXHAIGAtxkPSgclwQ",
    "photoUrls": ["CsqXCulpfbiTOtpRXmUz", "BTEjfxkAsBfNasHwaHom", "osMdzZKMCElFxsEMRitn", "GKKLHNWatmgjcBxietmS"],
    "tags": [],
    "status": "sold"
}]  

Ocp-Apim-Subscription-Key trong API Settings

Ocp-Apim-Subscription-Key là một API key được tạo tự động bởi Azure API Management cho mỗi subscription.
Nó được sử dụng để xác thực (authenticate) các request gửi đến API.
Key này xác định người dùng nào được phép truy cập và kiểm soát quyền hạn của họ thông qua Products.

Trước khi sử dụng Ocp-Apim-Subscription-Key, bạn cần đảm bảo rằng API yêu cầu key này được bật trong phần Settings.

1. Truy cập vào Azure Portal và mở API Management Instance.
2. Vào tab APIs > chọn API mà bạn muốn bật key.
3. Trong tab Settings:
•  Tìm Subscription required (có thể ở mục Authentication).
•  Đảm bảo Checkbox được bật (Checked). Điều này bắt buộc request phải cung cấp Ocp-Apim-Subscription-Key.
4. Nhấn Save để lưu cấu hình.

Lấy Ocp-Apim-Subscription-Key

Sau khi bật tùy chọn, bạn cần sử dụng Subscription Key trong request. Làm theo các bước sau để lấy key:

• Truy cập Azure API Management Instance.
• Vào Subscriptions.
• Tìm subscription của bạn (ví dụ: Starter, Unlimited) > Chọn subscription.
• Copy Primary Key hoặc Secondary Key.

 Sau đó, bạn quay lại API pet/findByStatus, thực hiện request, sẽ nhận được response

{
    "statusCode": 401,
    "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API."
}

Bổ sung key 'Ocp-Apim-Subscription-Key' vào header với value subscription key vừa tạo ở bước trên. Bạn sẽ nhận được kết quả như ở ví dụ 1

Chương trình dưới đây minh họa bằng Console Application

var ocpApimKey = "<your-subscription-key>";
var findByStatusUrl = "https://<your-apim-url>.azure-api.net/petstore/pet/findByStatus?status=sold";

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", ocpApimKey);

var response = await client.GetAsync(findByStatusUrl);
if (response.IsSuccessStatusCode)
{
    var data = await response.Content.ReadAsStringAsync();
    System.Console.WriteLine(data);
}
else
{
    System.Console.WriteLine($"Error: {response.StatusCode}");
}

Chúc các bạn thành công!