Với OpenAPI, thay vì các phần tử XML, bạn có một tập hợp các đối tượng JSON, với một lược đồ cụ thể xác định cách đặt tên, thứ tự và nội dung của chúng. Tệp JSON này (thường được thể hiện bằng YAML thay vì JSON) mô tả từng phần trong API của người dùng. Bằng cách mô tả API của người dùng ở định dạng tiêu chuẩn, các công cụ xuất bản có thể phân tích cú pháp theo chương trình thông tin về API và hiển thị từng thành phần trong một màn hình tương tác, cách điệu.

Hình 1: Giới thiệu về OpenAPI

Đặc tả OpenAPI Specification 3.0.3 (OAS) xác định một giao diện chuẩn, không có ngôn ngữ cho các API RESTful cho phép cả người và máy tính khám phá và hiểu các khả năng của dịch vụ mà không cần truy cập vào mã nguồn, tài liệu hoặc thông qua kiểm tra lưu lượng mạng. Khi được xác định đúng, người dùng có thể hiểu và tương tác với dịch vụ từ xa với một lượng logic triển khai tối thiểu. Sau đó, định nghĩa OpenAPI có thể được sử dụng bởi các công cụ tạo tài liệu để hiển thị API, các công cụ tạo mã để tạo máy chủ và máy khách bằng các ngôn ngữ lập trình khác nhau, công cụ kiểm tra và nhiều trường hợp sử dụng khác.

OAS được xây dựng dựa trên bộ mã nguồn mở Swagger vào cuối năm 2015 và cho ra đời bản thảo đầu tiên vào 28.02.2017. Đến 26.06.2017, đặc tả OpenAPI phiên bản 3.0.0 đầu tiên được phát hành và được triển khai rộng rãi trên môi trường mạng. Phiên bản hiện tại OpenAPI Specification 3.0.3 là phiên bản vá lỗi và hoạn thiện cuối cùng của đặc tả này vào ngày 20.02.2020.

Hình 2: Giao diện viết API

Các giá trị từ OAS

Sau một thời gian dài được tung lên môi trường mạng từ thời điểm năm 2017 và qua các bản vá lỗi, OAS đã chứng minh được các giá trị về nhiều mặt lợi ích:

- Phát triển sản phẩm được rút ngắn thời gian:

Thế giới đang chứng kiến được sự mạnh mẽ phát triển của lĩnh vực Open API. Một trong những cái tên đáng chú ý có thể kể đến ProgrammableWeb với việc chia sẻ kho 15.000 API của mình. Người dùng hay lập trình viên có thể dễ dàng thấy các API mới được cập nhật mỗi ngày. Các lập trình viên có thể chèn các đoạn mã API này vào các dự án phần mềm họ đang thực hiện và tung sản phẩm ra thị trường nhanh chóng hơn. Việc thiết kế các phần nhỏ, tiểu tiết của sản phẩm tổng thể đã được thay thế bởi các đoạn mã API. Một số nhà cung cấp dịch vụ khác lại chọn hướng phát triển chuyên sâu hướng tới nhóm đối tượng hay khách hàng cụ thể, điều đó khiến giá trị sản phẩm API của họ cao hơn và họ cũng không mất nhiều thời gian để làm một sản phẩm tổng thể.

- Hướng tới cốt lõi của sản phẩm:

Ngoài lợi ích về việc giúp các lập trình viên hoàn thiện sản phẩm nhanh chóng, OAS có một lợi ích to lớn khác chính là giúp các nhà phát triển, các lập trình viên tập trung vào chất riêng cho sản phẩm của họ, điều này là bởi OAS giúp họ giảm bớt các phần “râu ria” đi kèm với sản phẩm mà vẫn đúng theo mong muốn của họ.

- Các sản phẩm API sẽ ngày một chất lượng hơn trước:

 Nhiều API hoạt động hiệu quả và linh hoạt hơn các API khác, những API kém hiệu quả hơn thường là do bị bó buộc vào yêu cầu sản phẩm trong nội bộ công ty. Trong khi đó, các API phát triển bởi “bên thứ ba” với mục tiêu hướng tới nhiều hiệu năng, thân thiện người dùng hơn lại được ưa chuộng hơn. Các công ty thường coi nhẹ khâu xây dựng và bảo trì các tính năng họ có thể chèn vào sản phẩm của mình bằng các Open API. Cuối cùng thì các nhà cung cấp Open API “bên thứ ba” lại thu hút người sử dụng nhiều hơn, mặt khác họ thu được một khối dữ liệu lớn hơn để tạo ra hiệu ứng lan tỏa. (network effect). Những hiệu ứng lan tỏa này có thể là giá thành rẻ hơn, thỏa thuận cung cấp dịch vụ tốt hơn cho đến khả năng sử dụng AI phân tích các loại dữ liệu người dùng. Ví dụ như công ty Signifyd chuyên cung cấp Open API phân tích các hành vi gian lận trong sử dụng sản phẩm mà cụ thể là API này sẽ tổng hợp dữ liệu giao dịch từ hàng trăm công ty, cho phép họ hiểu sâu hành vi của một lượng lớn các vụ gian lận hơn bất cứ một công ty đơn lẻ nào có thể nhìn ra.

Các mô hình kinh doanh và sử dụng OAS phổ biến

Hiện tại có 3 mô hình kinh doanh chính với OAS

- Cung cấp API hoàn toàn miễn phí:

Việc cung cấp API miễn phí có nhiều mục đích nhưng về cơ bản nó giúp việc quảng bá rộng dãi API một cách nhanh chóng mà hiệu quả hơn việc trả tiền quảng cáo hay chờ tính quen thuộc với người dùng. Ví dụ là Facebook cho phép nhúng nút “like” vào các trang web khác. Điều này giúp nút Like của Facebook lan tỏa khắp nơi trên Internet, khẳng định nền tảng “social networking” số một thế giới của Facebook.

- Trả tiền để sử dụng:

Đơn giản như cách gọi của nó, người dùng cần trả tiền tiền để được sử dụng các dịch vụ của bên cung cấp API. Tuy nhiên, kinh doanh từ API là một mô hình kinh doanh số tiềm năng có từ thời điểm 2016, dưới đây là một số mô hình nổi bật

+ “Pay As You Go”: Được hiểu là trả tiền theo nhu cầu thực tế sử dụng. Điển hình cho mô hình này là dịch vụ Cloud của Amazon, đó là Amazon Web Services (AWS). AWS cung cấp các dịch vụ cơ sở hạ tầng như máy chủ, cơ sở dữ liệu, lưu trữ, hạ tầng mạng... với chính sách giá Pay-As-You-Go. Các dịch vụ của AWS không có mức chi phí tối thiểu, cũng không cần phải cọc trước hay hợp đồng dài hạn. Tất cả phụ thuộc vào người dùng, trả phí theo đúng thời gian sử dụng thực tế. Nhìn nhận về việc cho thuê hạ tầng máy chủ với các hệ thống cũ, việc mua và lắp đặt hệ thống mất rất nhiều thời gian, dẫn đến việc các tài nguyên phải được mua trước theo dự báo nhu cầu, việc đó dẫn đến tổ chức phải bỏ ra một số vốn lớn ban đầu (capex), và gây lãng phí hoặc nếu không thì lại không đáp ứng được nhu cầu thật. Từ những lợi ích và tiện lợi của AWS, rất nhiều công ty lớn đã sử dụng AWS thay vì phát triển hệ thống cơ sở hạ tầng của mình hoặc thuê các loại hình trung tâm dữ liệu truyền thống, nó quá tiện lợi và giảm thiểu chi phí. Một ví dụ cụ thể là Netflix, một công ty cung cấp dịch vụ xem phim trực tuyến lớn nhất thế giới. Netflix đã sử dụng AWS cho gần như toàn bộ hệ thống streaming của họ, Netflix sử dụng hàng chục nghìn máy chủ và lưu trữ hàng chục petabytes dữ liệu trên dịch vụ AWS bởi yếu tố linh hoạt trong quản trị và giá thành tổ chức với phương thức tính giá mới này.

+ “Freemium”: Được hiểu là miễn phí tính năng cơ bản, trả tiền cho tính năng cao cấp. Với mô hình này, người dùng được dùng miễn phí sản phẩm và dịch vụ được coi là cơ bản nhất của ứng dụng, điều này giúp xây dựng thói quen sử dụng ứng dụng ở khách hàng, phí chỉ được tính khi khách hàng muốn sử dụng các tính năng mở rộng hay đặc biệt hơn. Đây cũng là một mô hình thông dụng mà nhiều nhà cung cấp API thương mại hay sử dụng. Mô hình hình có một lợi thế lớn là dễ dàng tiếp cận tập người dùng có nhu cầu cơ bản, kích thích thói quen sử dụng để thu thập dữ liệu người dùng rồi từ đó xây dựng các tính năng tích hợp mở rộng có sức hút hơn. Các dịch vụ cao cấp cũng nhờ thế mà có thể có một số nhỏ người dùng trả tiền hay nhóm người dùng doanh nghiệp tổ chức khi tập người dùng đã trở nên đủ nhiều và đa dạng. Ví dụ, dịch vụ Google Cloud Vision API cho phép người dùng sử dụng miễn phí 1.000 unit/tháng; hoặc dịch vụ Google Maps API cũng dùng chính sách freemium.

+ Ngoài ra còn rất nhiều mô hình khác như: transaction fee, unit-based, …

- Được trả tiền khi sử dụng:

Đối với mô hình này, chủ yếu là tạo ra lợi ích cho bên cung cấp API. Vì vậy, nhà cung cấp muốn khuyến khích và tạo động lực cho việc sử dụng API của họ một cách cởi mở là trả tiền cho người dùng. Còn các hình thức trả phí cho nhà phát triển rất đa dạng tùy thuộc vào ngành nghề và phương pháp kinh doanh của từng nhà cung cấp.

Trên thế giới hiện nay thì có khá nhiều API trả tiền nhưng nổi tiếng nhất trong những API trả tiền là Amazon Advertising API. API này cho phép nhà phát triển truy cập và lấy thông tin về hàng triệu sản phẩm mà Amazon đang bán trên hệ thống của họ trên toàn cầu như: Sách báo, âm nhạc, đồ điện tử, đồ gia dụng... Từ đó, nhà phát triển có thể dùng thông tin này để quảng cáo các sản phẩm trên trang web của mình. Nếu người dùng mua một sản phẩm mà do nhà phát triển giới thiệu đến, thì Amazon sẽ trả cho người giới thiệu một tỷ lệ hoa hồng quảng cáo nhất định tùy theo mặt hàng. Những hình thức này người ta gọi là tiếp thị liên kết (affiliate marketing). Đây là phương thức tiếp thị dựa trên nền tảng công nghệ Internet; so với cách quảng cáo truyền thống cần đăng ký và cọc trước tiền quảng cáo hay thành công nằm ở tần xuất và ảnh hưởng của quảng cáo thì cách tiếp thị mới tạo ra một cách tiếp cận hiệu quả hơn và hợp lí hơn. Các bên liên kết với nhau dựa trên nền tảng API để tiếp thị cho sản phẩm.

Nội dung chi tiết

1. Định nghĩa

OAS là một định dạng mô tả API dành cho REST APIs. Một tệp OpenAPI cho phép người dùng mô tả toàn bộ API bao gồm:

- Cho phép những endpoints (/users) và cách thức hoạt động của mỗi endpoint (GET /users, POST /users)

- Các tham số đầu vào và ra của từng hoạt động

- Phương thức xác thực

- Thông tin liên lạc, chứng chỉ, điều khoản sử dụng và những thông tin khác

OAS cần tạo mẫu đường dẫn đề cập đến việc sử dụng các biểu thức mẫu, được phân tách bằng dấu ngoặc nhọn ({}) để đánh đấu một phần của đường dẫn URL là có thể thay thế bằng cách sử dụng các tham số đường dẫn.

Đối với các tiêu chuẩn kết nối, OAS tuân thủ RFC6838. Đối với mã trạng thái HTTP, nó được sử dụng để chỉ ra trạng thái của hoạt động được thực thi. Các mã trạng thái có sẵn được xác định bởi RFC7231 và các mã trạng thái đã đăng ký được liệt kê theo tổ chức cấp phát số hiệu chuẩn Internet (IANA).

2. Định dạng

Bản thân tài liệu OpenAPI tuân theo Đặc điểm kỹ thuật OpenAPI là một đối tượng JSON, có thể được biểu diễn ở định dạng JSON hoặc YAML.

Ví dụ: nếu một trường có giá trị mảng, thì biểu diễn mảng JSON sẽ được sử dụng:

Hình 3: Mảng JSON theo OAS

Tất cả các tên trường trong đặc tả đều phân biệt chữ hoa chữ thường. Điều này bao gồm tất cả các trường được sử dụng làm khóa trong miêu tả, ngoại trừ trường hợp được ghi chú rõ ràng rằng các khóa không phân biệt chữ hoa chữ thường.

Lược đồ hiển thị hai loại trường: trường cố định, có tên được khai báo và trường có mẫu, khai báo mẫu regex cho tên trường.

Các trường có mẫu phải có tên duy nhất với đối tượng mà nó đại diện.

Để duy trì khả năng thay đổi giữa các định dạng YAML và JSON, YAML phiên bản 1.2 được khuyến cáo cùng với một số ràng buộc bổ sung:

- Các thẻ phải được giới hạn ở những thẻ được bộ quy tắc lược đồ JSON cho phép .

- Các khóa được sử dụng trong bản đồ YAML phải được giới hạn trong một chuỗi vô hướng, như được định nghĩa bởi bộ quy tắc lược đồ YAML Failsafe.

Khuyến cáo rằng tài liệu OpenAPI gốc phải được đặt tên: openapi.json hoặc openapi.yaml.

Lưu ý: Mặc dù các API có thể được định nghĩa bởi các tài liệu OpenAPI ở định dạng YAML hoặc JSON, các cơ quan phản hồi và yêu cầu API cũng như nội dung khác không bắt buộc phải là JSON hoặc YAML.

3. Các loại dữ liệu

Các kiểu dữ liệu ban đầu trong OAS dựa trên các kiểu được hỗ trợ bởi Bản thảo Wright của lược đồ JSON (JSON Schema: A Media Type for Describing JSON Documents draft-wright-json-schema-00). Lưu ý rằng integer với tư cách là một loại cũng được hỗ trợ và được định nghĩa là số JSON không có phần phân số hoặc số mũ. nullkhông được hỗ trợ như một loại (xem nullablegiải pháp thay thế). Mô hình được định nghĩa bằng Đối tượng lược đồ, là một tập con mở rộng của Đặc tả lược đồ JSON Wright Draft 00.

Primitives có một định dạng sửa đổi tùy chọn: “format”. OAS sử dụng một số định dạng đã biết để xác định chi tiết kiểu dữ liệu đang được sử dụng. Tuy nhiên, để hỗ trợ nhu cầu tài liệu, “format” định dạng là định dạng được “string” miêu tả mở và có thể có bất kỳ giá trị nào.

Các định dạng chẳng hạn như "email", "uuid"v.v., có thể được sử dụng mặc dù không được xác định bởi đặc tả này. Các kiểu không kèm theo thuộc “format” tính tuân theo định nghĩa kiểu trong Lược đồ JSON. Các công cụ không nhận ra một cụ thể “format” có thể mặc định trở lại “type” một mình, như một “format” ở thể không được chỉ định.

Các định dạng được xác dịnh bởi OAS là:

4. Định dạng văn bản đa dạng thức

Trong suốt các trường thông số kỹ thuật, “description" được ghi nhận là hỗ trợ định dạng đánh dấu CommonMark. Trường hợp công cụ OpenAPI hiển thị văn bản đa dạng thức thì nó phải hỗ trợ, ở mức tối thiểu, cú pháp đánh dấu như được mô tả bởi CommonMark 0.27. Việc xây dựng API có thể chọn bỏ qua một số tính năng CommonMark để giải quyết các mối lo ngại về bảo mật.

5. Phần mở rộng đặc điểm

Trong khi Đặc điểm kỹ thuật OpenAPI cố gắng đáp ứng hầu hết các trường hợp sử dụng, dữ liệu bổ sung có thể được thêm vào để mở rộng thông số kỹ thuật tại một số điểm nhất định.

Các thuộc tính tiện ích mở rộng được triển khai dưới dạng các trường mẫu luôn có tiền tố là "x-".

6. Bảo mật với yếu tố lọc bỏ

Một số đối tượng trong Đặc tả OpenAPI có thể được khai báo và vẫn trống hoặc bị loại bỏ hoàn toàn, mặc dù chúng vốn dĩ là cốt lõi của tài liệu API.

Lý do là để cho phép một lớp kiểm soát truy cập bổ sung đối với tài liệu. Mặc dù không phải là một phần của bản đặc tả, nhưng một số thư viện có thể chọn cho phép truy cập vào các phần của tài liệu dựa trên một số hình thức xác thực / ủy quyền.

Hai ví dụ về điều này:

- Các Paths Object có thể rỗng. Nó có thể phản trực giác, nhưng điều này có thể cho người xem biết rằng họ đã đến đúng nơi, nhưng không thể truy cập bất kỳ tài liệu nào. Họ vẫn có quyền truy cập vào đối tượng thông tin có thể chứa thông tin bổ sung về xác thực.

- Các đường dẫn mục Object có thể rỗng. Trong trường hợp này, người xem sẽ biết rằng đường dẫn tồn tại, nhưng sẽ không thể thấy bất kỳ hoạt động hoặc tham số nào của nó. Điều này khác với việc ẩn chính đường dẫn khỏi đối tượng đường dẫn, bởi vì người dùng sẽ nhận thức được sự tồn tại của nó. Điều này cho phép nhà cung cấp tài liệu kiểm soát tốt những gì người xem có thể nhìn thấy.

Tạm kết

Như vậy, phần một của tiêu chuẩn OpenAPI phiên bản 3.0.3 đã chỉ ra những nét cơ bản nhất, các khái niệm của tiêu chuẩn này, đồng thời chia sẻ về tính ứng dụng và hiệu quả của tiêu chuẩn mang tính thực tiễn cao cho người sử dụng cả về mặt kinh tế và hiệu năng sử dụng. Phần tiếp theo sẽ đi sâu vào chia tiết các đối tượng của tiêu chuẩn này.

Vũ Cao Minh Đức

Tài liệu tham khảo

- https://swagger.io/specification/

- https://tools.ietf.org/html/rfc6838

- https://tools.ietf.org/html/rfc7231

- https://yaml.org/spec/1.2/spec.html#id2802346