FPT API Management

1. Đăng ký dịch vụ API MANAGEMENT

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

Để đăng ký mới 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.

Bước 1: Trên menu của FPT Portal chọn Api Management > Create.

Bước 2: Nhập thông tin Username và chọn Plan và Pricing.

Bạn có thể tham khảo cấu hình cụ thể của từng plan theo bảng dưới đây:

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

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

Hoặc để chủ động truy cập vào trang quản trị ApiManager Application, người dùng có thể vào FPT Portal và chọn Start trên API Management.

2. Khai báo Rest API

Sau khi đăng ký dịch vụ thành công, các thao tác cấu hình của API Management sẽ được thực hiện toàn bộ trên ApiManager Application. Đầu tiên bạn cần khai báo các API đang cần quản lý lên hệ thống để quản trị tập trung trên API Management.

Bước 1: Ở menu Application > API Manager > Rest Apis. Chọn Create.

Bước 2: Nhập các thông tin cần thiết:

• Name: Tên API.
• Title: Tiêu đề cho API.
• Base path: Phần đường dẫn để phía client call vào sau khi public API.
• Target endpoint: Endpoint của API đã có sẵn, 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. Hiện tại đang có ba phương thức được sử dụng là Basic Authentication, OAuth và Api Key.

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

Bước 3: Chọn OK để tiến hành khởi tạo REST APIs.

3. Khai báo Product

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

Bước 1: Ở menu Application > API Manager > Products, chọn Create.

Bước 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.

Bước 3: Chọn OK để tiến hành tạo Product.

4. Gắn APIs vào Product

Để gán API vào một Product, bạn thao tác như sau:

Bước 1: Ở Product Management, chọn Product cần gán API. Chọn Register API.

Bước 2: Chọn Register.

Bước 3: Chọn API cần gán vào Product và chọn Select.

Bước 4: Chọn OK để lưu.

• Product và API liên kết với nhau theo mối quan hệ Nhiều – Nhiều, vì vậy một Product có thể gán nhiều APIs và một API cũng có thể xuất hiện cùng lúc trong nhiều product.
• Product sẽ ảnh hưởng tới việc group API trong product đó được publish ra tới loại consumer nào.

5. Tạo Site mới

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

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

Bước 1: Ở menu Application > API Manager > Sites, chọn Create.

Bước 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 trước đó.
• Gateway: Chọn gateway trong danh sách đã được admin khai báo trước đó.
• Portal: Chọn Portal trong danh sách đã được admin khai báo trước đó.

Bước 3: Chọn OK để tiến hành tạo Site.

6. Staging product

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

Để gán product vào site, bạn thao tác như sau:

Bước 1: Ở Product Management, chọn Product cần pubic lên Site > Staging.

Bước 2: Chọn Staging to New site.

Bước 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 đó.

Bước 4: Chọn OK.

• Product và Site liên kết với nhau theo mối quan hệ Nhiều – Nhiều, vì vậy một Site có thể gán nhiều Product và một Product cũng có thể xuất hiện cùng lúc trong nhiều Site.
• Site sẽ quyết định xem product nào được show ra trên site đó (và các API trong product con)

7. Publish product

Sau khi product được stage lên một site, thì bản chất product vẫn đang ở trạng thái private. Lúc này consumer chưa dùng được các API trong product đó. Bạn cần thực hiện publish product thì consumer mới sử dụng được.

Để thực hiện publish Product, bạn thao tác như sau:

Bước 1: Ở menu API Manger, chọn Sites.

Bước 2: Chọn Site chứa Product cần Publish > Chọn Product.

Bước 3: Chọn Product cần Publish > Chọn Publish.

8. Tạo Consumers mới

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

Để tạo Consumer, bạn thao tác như sau:

Bước 1: Ở menu API Manger, chọn Consumers > Create.

Bước 2: Nhập các thông tin theo yêu cầu:

• Name: Tên Consumers.
• Site: Chọn site Consumers 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 Authenticate.
• Confirm password: Xác nhận lại mật khẩu.
• Max per second: Điền số lần client có thể gọi API trên giây.
• Max per minute: Điền số lần client có thể gọi API trên phút.
• Max per hour: Điền số lần client có thể gọi API trên giờ.

• 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 tự với API cần sử dụng.
  • Ví dụ: API của bạn dùng phương thức xác thực (PTXT) là Basic thì PTXT của Consumer cũng phải là Basic. Nếu 1 consumer có nhu cầu sử dụng nhiều API với nhiều PTXT khác nhau thì bạn cần khai báo đủ các phương thức xác thực cho Consumer đó. Sau đó tùy vào sử dụng API nào mà sử dụng PTXT cho hợp lý.

Bước 3: Chọn OK để tiến hành tạo.

9. Subscribe product

Sau khi tạo Consumer xong, để sử dụng được các API có trong Product thì nhà cung cấp phải chỉ định Consumer subcribe một Product.

Bước 1: Ở Consumer Management, chọn consumer và click chọn Product subscription.

Bước 2: Chọn Subscribe product.

Bước 3: Chọn Product.

Product bắt buộc phải ở trạng thái publish thì consumer mới có thể chọn trong giao diện subcribe.

Bước 4: Chọn OK để lưu.

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

10. Nhận thông tin từ API Provider

Để có thể bắt đầu sử dụng, client sẽ 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. Hiện tại đang hỗ trợ Basic hoặc API Key.
• Nếu Authorization là Basic:
  • Username: Tên user với cấu trúc:

Username = UsernameProvider + tên site + usernameConsumer.

Ví dụ: demo123.sitedemo.demoacc

Hoặc có thể lấy theo hướng dẫn Lấy thông tin xác thực của Consumer.

• Password: Mật khẩu của user đã 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 ở phần
  • Add to: Header.

• Site được ủy quyền.

11. Sử dụng Postman

Khi đã có đủ thông tin, client có thể sử dụng Postman để bắt đầu dùng API được cung cấp từ API Management.

Bước 1: Nhập endpoint và chọn method gọi API.

Bước 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.

Bước 3: Nhập các request body, param khác để gọi API và chọn Send.

Bước 4: Nhận kết quả trả về.

• Status message 2xx: Gọi API thành công
• Status message 4xx – 5xx: Lỗi – báo cho FCI để được hỗ trợ

Lưu ý: Checklist check lỗi sẽ tuần tự như sau:

• Kiểm tra username, password.
• Báo API Provider kiểm tra quyền của client với API trước.
• Kiểm tra API đã khai báo đúng hay chưa, param bị thiếu header gì hay không?
• Kiểm tra API có bị lỗi hay không ?
• Báo FCI kiểm tra gateway.