Xây dựng và sử dụng REST APIs trong Oracle APEX

Trong các ứng dụng hiện đại, REST API là một phần rất quan trọng của kiến trúc tích hợp. Một ứng dụng Oracle APEX không chỉ hiển thị dữ liệu cho người dùng trong trình duyệt, mà còn có thể kết nối với mobile app, hệ thống bên ngoài, dịch vụ thanh toán, hệ thống kế toán, CRM, ERP hoặc các ứng dụng nội bộ khác.

Oracle APEX kết hợp với ORDS giúp việc xây dựng và sử dụng REST API trở nên khá thuận tiện. Bạn có thể expose dữ liệu hoặc PL/SQL logic thành API, đồng thời cũng có thể consume API từ bên ngoài bằng REST Data Source hoặc package APEX_WEB_SERVICE.

Bài viết này tập trung vào cách xây dựng và sử dụng REST APIs trong Oracle APEX theo hướng dễ hiểu, thực tế và phù hợp với ứng dụng doanh nghiệp. Nội dung sẽ đi từ khái niệm REST API, vai trò của ORDS, cách thiết kế endpoint, cách trả response, bảo mật API và cách APEX consume API từ hệ thống bên ngoài.

REST API là gì?

REST API là cách để các hệ thống giao tiếp với nhau qua HTTP. Thay vì cho ứng dụng bên ngoài kết nối trực tiếp vào database, bạn tạo ra các endpoint có kiểm soát. Mỗi endpoint đại diện cho một tài nguyên hoặc một hành động cụ thể.

Ví dụ:

• GET /customers: lấy danh sách khách hàng.
• GET /customers/100: lấy chi tiết khách hàng có ID 100.
• POST /customers: tạo khách hàng mới.
• PUT /customers/100: cập nhật khách hàng có ID 100.
• DELETE /customers/100: xóa hoặc vô hiệu hóa khách hàng.

REST API giúp hệ thống giao tiếp rõ ràng, tách biệt và dễ kiểm soát hơn so với việc chia sẻ trực tiếp quyền truy cập database.

Lược đồ tổng quan: Client, Request, Server và Response

Flow này là nền tảng của hầu hết tích hợp API. Client gửi request đến endpoint. ORDS nhận request, xác định module/template/handler cần chạy, xử lý dữ liệu trong database hoặc PL/SQL, rồi trả response về cho client.

ORDS đóng vai trò gì?

ORDS, viết tắt của Oracle REST Data Services, là lớp trung gian giúp expose database logic thành RESTful services. ORDS nhận HTTP request từ bên ngoài và chuyển nó thành SQL hoặc PL/SQL call ở phía Oracle Database.

Trong APEX, khi bạn vào phần RESTful Services, các API được tổ chức theo một số khái niệm chính:

• Module: nhóm endpoint cùng chủ đề, ví dụ customers, orders, products.
• Template: pattern URL, ví dụ customers/:id.
• Handler: xử lý HTTP method cụ thể như GET, POST, PUT hoặc DELETE.
• Privilege: cơ chế bảo vệ endpoint nếu API cần authentication/authorization.

Khi thiết kế API, bạn nên đặt tên module và endpoint rõ ràng, dễ hiểu và phản ánh tài nguyên nghiệp vụ.

Xây dựng REST API trong Oracle APEX/ORDS

Một REST API đơn giản thường bắt đầu bằng việc tạo module, sau đó tạo template và handler. Ví dụ, bạn muốn expose danh sách khách hàng.

Endpoint có thể là:

GET /ords/my_schema/api/customers

Handler phía sau có thể chạy SQL:

select customer_id,
       customer_name,
       email,
       phone_number,
       status
from customers
where status = 'ACTIVE'
order by customer_name

Khi client gọi endpoint này, ORDS sẽ trả dữ liệu dạng JSON.

Ví dụ GET API lấy chi tiết một bản ghi

Với endpoint lấy chi tiết khách hàng, bạn có thể dùng template có parameter:

GET /ords/my_schema/api/customers/:id

Handler có thể dùng bind variable:

select customer_id,
       customer_name,
       email,
       phone_number,
       status
from customers
where customer_id = :id

Đây là một pattern rất phổ biến: URL chứa ID, handler dùng ID đó để truy vấn dữ liệu. Cần đảm bảo endpoint chỉ trả dữ liệu người gọi được phép xem.

Ví dụ POST API tạo dữ liệu

Với API tạo khách hàng mới, client thường gửi JSON body qua HTTP POST.

POST /ords/my_schema/api/customers

{
  "customer_name": "Nguyen Van A",
  "email": "a@example.com",
  "phone_number": "0900000000"
}

Handler có thể gọi PL/SQL để parse JSON và insert dữ liệu:

begin
  customer_api.create_customer(
    p_customer_name => :customer_name,
    p_email         => :email,
    p_phone_number  => :phone_number
  );
end;

Với các thao tác ghi dữ liệu, bạn nên ưu tiên gọi package PL/SQL thay vì viết toàn bộ logic trực tiếp trong handler. Package giúp gom business rules, validation, logging và xử lý lỗi vào một nơi dễ kiểm soát hơn.

HTTP methods nên dùng đúng ý nghĩa

Khi thiết kế REST API, bạn nên dùng HTTP methods theo đúng mục đích:

• GET: lấy dữ liệu, không thay đổi dữ liệu.
• POST: tạo dữ liệu mới hoặc thực hiện một hành động nghiệp vụ.
• PUT: cập nhật toàn bộ hoặc cập nhật theo định nghĩa của API.
• DELETE: xóa hoặc vô hiệu hóa dữ liệu.

Việc dùng đúng method giúp API dễ hiểu hơn cho người consume và cũng dễ kiểm soát bảo mật hơn.

Response nên rõ ràng và nhất quán

Một API tốt không chỉ trả dữ liệu đúng, mà còn trả response rõ ràng. Client cần biết request thành công hay thất bại, lỗi do validation, lỗi không có quyền, hay lỗi hệ thống.

Ví dụ response thành công:

{
  "status": "success",
  "customer_id": 100,
  "message": "Customer created successfully"
}

Ví dụ response lỗi validation:

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Email is required"
}

Ngoài JSON body, bạn cũng nên dùng HTTP status code phù hợp:

• 200 OK: request thành công.
• 201 Created: tạo mới thành công.
• 400 Bad Request: request sai dữ liệu.
• 401 Unauthorized: chưa xác thực.
• 403 Forbidden: đã xác thực nhưng không có quyền.
• 404 Not Found: không tìm thấy tài nguyên.
• 500 Internal Server Error: lỗi hệ thống.

Bảo mật REST API

Không nên expose API quan trọng ở chế độ public nếu dữ liệu có tính nội bộ hoặc nhạy cảm. REST API cần được bảo vệ bằng authentication và authorization phù hợp.

Một số điểm cần lưu ý:

• Không để endpoint ghi dữ liệu ở chế độ public.
• Dùng OAuth2, bearer token hoặc cơ chế bảo vệ phù hợp với môi trường.
• Kiểm tra quyền ở server-side, không chỉ dựa vào client.
• Không trả dữ liệu nhạy cảm không cần thiết.
• Ghi log các request quan trọng.
• Giới hạn method được phép dùng.
• Validate input đầy đủ trước khi insert/update.

API là cổng vào hệ thống. Nếu thiết kế hời hợt, API có thể trở thành điểm rủi ro lớn hơn cả UI APEX.

Consume REST API trong Oracle APEX

Oracle APEX không chỉ dùng để build API, mà còn có thể consume API từ hệ thống khác. Có hai hướng phổ biến:

• Dùng REST Data Source để cấu hình declarative.
• Dùng package APEX_WEB_SERVICE để gọi API bằng PL/SQL.

REST Data Source phù hợp khi bạn muốn dùng API như một nguồn dữ liệu cho report, chart, form hoặc LOV. APEX_WEB_SERVICE phù hợp khi bạn cần kiểm soát request/response bằng PL/SQL, xử lý logic phức tạp hoặc gọi API trong process/package.

Dùng REST Data Source

REST Data Source là cách khai báo nguồn dữ liệu REST trong Shared Components. Sau khi cấu hình endpoint, authentication và mapping response, bạn có thể dùng nó trong APEX component.

Quy trình tổng quát:

1. Vào Shared Components.
2. Tạo REST Data Source.
3. Khai báo endpoint URL.
4. Cấu hình authentication nếu API yêu cầu.
5. Test request và kiểm tra response.
6. Map JSON response thành columns.
7. Dùng REST Data Source trong report hoặc component.

Cách này rất tốt khi bạn muốn APEX consume API theo hướng low-code/declarative.

Dùng APEX_WEB_SERVICE để gọi API

Nếu cần gọi API trong PL/SQL, bạn có thể dùng APEX_WEB_SERVICE. Ví dụ gọi GET request:

declare
  l_response clob;
begin
  l_response := apex_web_service.make_rest_request(
                  p_url         => 'https://api.example.com/customers',
                  p_http_method => 'GET'
                );

  dbms_output.put_line(l_response);
end;

Nếu API trả JSON, bạn có thể parse response bằng JSON functions hoặc package phù hợp. Trong APEX process, bạn có thể lấy dữ liệu response rồi set vào page item, insert vào table, hoặc hiển thị ra region.

Ví dụ POST request bằng APEX_WEB_SERVICE

Với POST request, bạn thường cần gửi JSON body.

declare
  l_body     clob;
  l_response clob;
begin
  l_body := '{
    "customer_name": "Nguyen Van A",
    "email": "a@example.com"
  }';

  apex_web_service.g_request_headers(1).name  := 'Content-Type';
  apex_web_service.g_request_headers(1).value := 'application/json';

  l_response := apex_web_service.make_rest_request(
                  p_url         => 'https://api.example.com/customers',
                  p_http_method => 'POST',
                  p_body        => l_body
                );

  dbms_output.put_line(l_response);
end;

Trong ứng dụng thật, không nên hard-code URL hoặc token trực tiếp trong process. Hãy dùng Web Credentials, application settings hoặc bảng cấu hình phù hợp.

Web Credentials

Nếu API cần authentication, APEX hỗ trợ Web Credentials để lưu thông tin xác thực. Đây là cách tốt hơn so với việc đặt token, username hoặc password trực tiếp trong code.

Web Credentials giúp:

• Tách thông tin bảo mật khỏi PL/SQL code.
• Dễ thay đổi credential theo môi trường dev/test/prod.
• Giảm nguy cơ lộ secret trong source code.
• Hỗ trợ các kiểu xác thực phổ biến như Basic, OAuth2 hoặc token-based tùy cấu hình.

Với các API production, việc quản lý credential đúng cách là bắt buộc.

API nên gọi package, không nên rải logic khắp nơi

Một lỗi thường gặp là viết quá nhiều logic trực tiếp trong REST handler hoặc page process. Ban đầu cách này nhanh, nhưng về lâu dài khó bảo trì.

Pattern tốt hơn:

• REST handler nhận request.
• Handler gọi package PL/SQL.
• Package validate input, kiểm tra quyền và xử lý nghiệp vụ.
• Package trả kết quả rõ ràng.
• Handler chuyển kết quả thành response JSON.

Ví dụ:

begin
  order_api.submit_order(
    p_order_id => :order_id,
    p_user     => :current_user
  );
end;

Cách này giúp API, APEX page và các job nội bộ có thể tái sử dụng cùng một business logic.

Test API bằng Postman hoặc curl

Trước khi consume API trong APEX, bạn nên test endpoint bằng Postman, curl hoặc công cụ tương tự. Điều này giúp tách lỗi API khỏi lỗi cấu hình APEX.

Ví dụ test GET bằng curl:

curl -X GET \
  https://example.com/ords/my_schema/api/customers \
  -H "Authorization: Bearer YOUR_TOKEN"

Ví dụ test POST:

curl -X POST \
  https://example.com/ords/my_schema/api/customers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_name":"Nguyen Van A","email":"a@example.com"}'

Nếu API chạy đúng trong Postman/curl nhưng lỗi trong APEX, lúc đó bạn kiểm tra Web Credentials, headers, wallet/SSL, proxy, request body hoặc parsing response.

Các lỗi thường gặp khi làm REST API trong APEX

Khi xây dựng và consume API, một số lỗi phổ biến gồm:

• Endpoint public ngoài ý muốn.
• Không validate input trước khi insert/update.
• Không dùng HTTP status code phù hợp.
• Response JSON không nhất quán giữa các endpoint.
• Hard-code token hoặc password trong PL/SQL.
• Không xử lý timeout hoặc lỗi kết nối khi gọi API bên ngoài.
• Không ghi log request/response quan trọng.
• Không version API, khiến thay đổi sau này làm hỏng client cũ.

Best practice khi thiết kế API

Một số nguyên tắc nên áp dụng:

• Đặt endpoint theo tài nguyên nghiệp vụ, ví dụ /customers, /orders.
• Dùng HTTP methods đúng ý nghĩa.
• Giữ response JSON nhất quán.
• Dùng package PL/SQL cho business logic.
• Bảo vệ API bằng authentication/authorization.
• Không trả dư dữ liệu nhạy cảm.
• Log lỗi và request quan trọng.
• Dùng version nếu API có khả năng thay đổi lớn, ví dụ /v1/orders.
• Viết tài liệu API cho người consume.

API càng được dùng bởi nhiều hệ thống, bạn càng cần thiết kế cẩn thận ngay từ đầu.

Kết luận

Oracle APEX và ORDS giúp việc xây dựng REST APIs trở nên dễ tiếp cận hơn rất nhiều. Bạn có thể expose dữ liệu và PL/SQL logic thành API, bảo vệ endpoint bằng cơ chế phù hợp, rồi để hệ thống khác gọi vào một cách có kiểm soát.

Ở chiều ngược lại, APEX cũng có thể consume REST API từ bên ngoài thông qua REST Data Source hoặc APEX_WEB_SERVICE. Đây là nền tảng quan trọng để xây dựng các ứng dụng tích hợp với mobile app, hệ thống nội bộ, dịch vụ cloud và nền tảng bên thứ ba.

Khi thiết kế API, hãy nhớ rằng API không chỉ là một URL trả JSON. API là hợp đồng giữa các hệ thống. Vì vậy cần rõ ràng, bảo mật, nhất quán, có validation, có logging và dễ bảo trì.