Hướng dẫn nhanh (Quick Starts)

ghi chú

Đối tượng sử dụng: API Provider.

Đăng ký dịch vụ API Management

Để đăng ký tài khoản API Provider, bạn cần được cấp quota dịch vụ. Hãy liên hệ với chúng tôi nếu có nhu cầu sử dụng.

1. Trên menu của FPT Portal, chọn Api Management > Create.

2. Nhập thông tin Username, chọn Plan và Pricing.

Tham khảo cấu hình từng plan theo bảng sau:

Plan	Mô tả	Số lượng site	Số lượng API	Số lượng Product
Pilot	User dùng site và product mặc định, không có chức năng tạo thêm site và product.	1	2	1
Normal	User dùng site và product mặc định, không có chức năng tạo thêm site.	1	Không giới hạn	1
Enterprise	User có thể tự tạo site và product.	Không giới hạn	Không giới hạn	Không giới hạn

Chức năng	Standard	Advanced	Premium
Transactions	Max: 250/s	Max: 1000/s	Max: 5000/s
Developer Portal	No	Yes	Yes
Custom Domain	Yes	Yes	Yes
Self-hosted Gateway	No	Yes	Yes
Message size	15KB	25KB	50KB
Logging retention	1 tháng	2 tháng	3 tháng
SLA	99.95%	99.99%	99.99%

3. Chọn Create. Hệ thống sẽ khởi tạo dịch vụ và thông báo tình trạng xử lý.

Sau khi khởi tạo thành công, người dùng được tự động chuyển hướng sang trang quản trị ApiManager Application.

Hoặc truy cập FPT Portal và chọn Start trên API Management để vào trang quản trị.

Khai báo REST API

Sau khi đăng ký dịch vụ, khai báo các API cần quản lý lên hệ thống để quản trị tập trung trên API Management.

1. Vào menu Application > API Manager > Rest Apis, chọn Create.

2. Nhập các thông tin cần thiết:
   • Name: Tên API.
   • Title: Tiêu đề cho API.
   • Base path: Đường dẫn để client gọi vào sau khi public API.
   • Use host group: Kích hoạt mode HA hoặc không.
   • Target endpoint: Endpoint của API hiện có, cần đưa ra cho consumer dùng.
   • Target Security: Thông tin xác thực của API.
   • Security method: Phương thức xác thực khi client sử dụng API. Hỗ trợ Basic Authentication, OAuth và Api Key.
   • Enable doc: Tạo doc cho API.
   • Enable validation schema: Thêm validation cho body request.

cảnh báo

Security method sẽ không thể thay đổi sau khi tạo. Hãy cẩn thận khi khai báo thông tin này.

3. Chọn OK để khởi tạo REST APIs.

Khai báo Product

Product là thực thể dùng để gom nhóm các API với nhau (chung mục đích sử dụng, chung client,…). Thay vì cấu hình từng API, bạn chỉ cần cấu hình một Product duy nhất.

1. Vào menu Application > API Manager > Products, chọn Create.

2. Nhập các thông tin theo yêu cầu:
   • Name: Tên product.
   • Title: Tiêu đề.
   • Visibility type: Chế độ hiển thị của Product, Public hoặc Closed.

3. Chọn OK để tạo Product.

Gắn APIs vào Product

1. Trong Product Management, chọn Product cần gán API, sau đó chọn Register API.

2. Chọn Register.

3. Chọn API cần gán vào Product, sau đó chọn Select.

4. Chọn OK để lưu.

ghi chú

• Product và API liên kết theo quan hệ nhiều–nhiều: một Product có thể gán nhiều API và một API có thể xuất hiện trong nhiều Product.
• Product ảnh hưởng đến việc nhóm API được publish tới loại consumer nào.

Tạo Site mới

Site là thực thể dùng để mapping các product với portal.

ghi chú

Nếu dùng gói Pilot hoặc Normal, bạn được cung cấp một site mặc định và không thể tạo thêm. Nâng cấp lên gói cao hơn nếu cần nhiều site.

1. Vào menu Application > API Manager > Sites, chọn Create.

2. Nhập các thông tin theo yêu cầu:
   • Name: Tên site.
   • Title: Tiêu đề.
   • Production mode: Chọn chế độ product.
   • Virtual area: Chọn khu vực trong danh sách đã được admin khai báo.
   • Gateway: Chọn gateway trong danh sách đã được admin khai báo.
   • Portal: Chọn Portal trong danh sách đã được admin khai báo.

3. Chọn OK để tạo Site.

Staging product

Sau khi có Product và Site, bạn cần stage (đặt) product vào site tương ứng trước khi sử dụng.

1. Trong Product Management, chọn Product cần public lên Site, sau đó chọn Staging.

2. Chọn Staging to New site.

3. Nhập các thông tin theo yêu cầu:
   • Product: Product cần gán vào Site.
   • Site to publish: Chọn site đã tạo trước đó.

4. Chọn OK.

ghi chú

• Product và Site liên kết theo quan hệ nhiều–nhiều: một Site có thể gán nhiều Product và một Product có thể xuất hiện trong nhiều Site.
• Site quyết định Product nào được hiển thị trên site đó (và các API trong product con).

Publish product

Sau khi stage, product vẫn ở trạng thái private. Consumer chưa dùng được các API trong product đó cho đến khi bạn thực hiện publish.

1. Vào menu API Manager, chọn Sites.

2. Chọn Site chứa Product cần publish, sau đó chọn Product.

3. Chọn Product cần publish, sau đó chọn Publish.

Tạo Consumers mới

Consumer là người dùng cuối sử dụng API, được toàn quyền sử dụng các API đã khai báo trong các Product được cấp quyền.

1. Vào menu API Manager, chọn Consumers > Create.

2. Nhập các thông tin theo yêu cầu:
   • Name: Tên Consumer.
   • Site: Chọn site Consumer có hiệu lực.
   • API Key: Tích chọn xác thực bằng API key hay không.
   • Title: Tiêu đề.
   • Password: Mật khẩu nếu dùng Basic Authentication.
   • Confirm password: Xác nhận lại mật khẩu.
   • Max per second: Số lần client có thể gọi API trên giây.
   • Max per minute: Số lần client có thể gọi API trên phút.
   • Max per hour: Số lần client có thể gọi API trên giờ.

ghi chú

• Có thể khai báo và sử dụng song song cả API Key và Password.
• Phương thức xác thực của Consumer phải tương ứng với API cần sử dụng. Ví dụ: nếu API dùng Basic Authentication thì Consumer cũng phải dùng Basic.

3. Chọn OK để tạo Consumer.

Subscribe product

Sau khi tạo Consumer, nhà cung cấp cần chỉ định Consumer subscribe một Product để Consumer có thể sử dụng các API trong Product đó.

1. Trong Consumer Management, chọn consumer, sau đó chọn Product subscription.

2. Chọn Subscribe product.

3. Chọn Product.

ghi chú

Product phải ở trạng thái published thì consumer mới có thể chọn trong giao diện subscribe.

4. Chọn OK để lưu.

Sau khi hoàn tất các bước trên, client đã có thể sử dụng các API mà nhà cung cấp đưa ra.

Nhận thông tin từ API Provider

Để bắt đầu sử dụng, client cần có các thông tin sau:

• Endpoint của API: Được cung cấp theo hướng dẫn lấy thông tin Endpoint của Product.
• Authorization: Phương thức xác thực của Consumer. Hỗ trợ Basic hoặc API Key.
  • Nếu Authorization là Basic:
    • Username: Cấu trúc: UsernameProvider.tênsite.usernameConsumer (ví dụ: demo123.sitedemo.demoacc). Hoặc lấy theo hướng dẫn lấy thông tin xác thực của Consumer.
    • Password: Mật khẩu đã khai báo ở bước tạo consumer.
  • Nếu Authorization là API Key:
    • Key: api-key
    • Value: Lấy theo hướng dẫn lấy thông tin xác thực của Consumer.
    • Add to: Header.
• Site được ủy quyền.

Sử dụng Postman

Khi đã có đủ thông tin, client có thể sử dụng Postman để gọi API từ API Management.

1. Nhập endpoint và chọn method gọi API.

2. Nhập thông tin Authorization:
   • Chọn Basic Auth và nhập Username/Password nếu Authorization là Basic.
   • Chọn API Key và nhập key nếu Authorization là API Key.

3. Nhập request body và các param khác, sau đó chọn Send.

4. Nhận kết quả trả về:
   • Status 2xx: Gọi API thành công.
   • Status 4xx–5xx: Lỗi — liên hệ FCI để được hỗ trợ.

mẹo

Checklist kiểm tra lỗi theo thứ tự:

1. Kiểm tra username, password.
2. Yêu cầu API Provider kiểm tra quyền của client với API.
3. Kiểm tra API đã khai báo đúng chưa, param hoặc header có bị thiếu không.
4. Kiểm tra API có bị lỗi không.
5. Yêu cầu FCI kiểm tra gateway.