Cơ bản về định nghĩa RESTful Web Service API specs sử dụng OpenAPI Specification

Bài viết được sự cho phép của tác giả Nguyễn Hữu Khanh

Mình đã hướng dẫn các bạn cách định nghĩa RESTful Web Service API specs sử dụng RAML. Có một cách khác để làm điều này là sử dụng OpenAPI Specification. Cụ thể như thế nào? Trong bài viết này, chúng ta sẽ cùng nhau tìm hiểu làm thế nào để định nghĩa RESTful Web Service API specs sử dụng OpenAPI Specification các bạn nhé!

Xem thêm các việc làm REST API hấp dẫn trên TopDev

Chúng ta sẽ sử dụng tập tin YAML hoặc JSON để định nghĩa API specs với OpenAPI Specification. Dưới đây là nội dung tập tin YAML định nghĩa API specs trong bài viết Giới thiệu về RAML sử dụng OpenAPI Specification:

openapi: 3.0.3
info:
title: Student Information Management System
version: "1.0"
servers:
- url: https://localhost:8081/api
paths:
/students:
get:
operationId: getStudents
summary: Get all students
responses:
200:
description: Get all students successfully
content:
application/json:
example: [{ "ID": 1, "code": "001", "name": "Khanh" }, { "ID": 2, "code": "002", "name": "Quan" }]
/students/{ID}:
get:
operationId: getStudentById
summary: Get a student by ID
parameters:
- name: ID
in: path
description: "ID of the Student"
required: true
schema:
type: string
responses:
200:
description: Get student information successfully
content:
application/json:
example: { "ID": 1, "code": "001", "name": "Khanh" }
delete:
operationId: deleteStudentById
summary: Delete a student by ID
parameters:
- name: ID
in: path
description: "ID of the Student"
required: true
schema:
type: string
responses:
200:
description: Delete student information successfully
content:
application/json:
example: { "message": "Student deleted!"}

Như các bạn thấy, tương tự như định nghĩa API specs với RAML, ở đầu tập tin YAML này, chúng ta sẽ định nghĩa một số thông tin overview về API specs của mình. Chúng ta sử dụng field openapi để định nghĩa OpenAPI Specification version chúng ta sẽ sử dụng để định nghĩa API specs, thông tin về API specs bao gồm mục đích của nó (field info.title), version của API specs này (info.version). Base URL sẽ được định nghĩa sử dụng field servers.url.

Các request URL sẽ được định nghĩa với section paths.

Chúng ta không định nghĩa các request URL với giá trị bắt đầu giống nhau theo kiểu extends như bên RAML được. Chúng ta chỉ có thể gom các request có HTTP method khác nhau nhưng cùng một request URL. Trong ví dụ trên thì request URL “/students/{ID}” được định nghĩa với GET và DELETE method, chúng ta có thể gom 2 request URL này lại với nhau.

Chúng ta có thể sử dụng field operationId để identify cho mỗi request URL. Giá trị của field này là duy nhất trong 1 API specs cho mỗi request URL.

Tương tự như RAML, chúng ta cũng có thể định nghĩa response cho mỗi response status code, mỗi response có thể có kiểu dữ liệu khác nhau. Trong ví dụ của mình thì đó là application/json.

Để định nghĩa parameter cho các request URL, chúng ta sẽ sử dụng section parameters trong mỗi request. Các parameter có thể là path parameter, query parameter hay nằm trong header, cookie. Chúng ta sử dụng field in của mỗi parameter để khai báo điều này.

OpenAPI cũng hỗ trợ nhiều kiểu dữ liệu khác nhau như RAML. Các bạn có thể tham khảo thêm ở đây các bạn nhé!

Việc định nghĩa API specs trước khi bắt tay vào implement API sẽ giúp chúng ta thống nhất được API contract, các bên liên quan chỉ cần follow theo API contract này để sử dụng, giảm thiểu rất nhiều rủi ro có thể xảy ra. Hãy suy nghĩ tới nó trước khi bắt đầu implement các API RESTful Web Service các bạn nhé!

Bài viết gốc được đăng tải tại huongdanjava.com

Có thể bạn quan tâm:

• Định nghĩa request URL trong ứng dụng Jakarta EE RESTful Web Services
• REST Web service: Tạo ứng dụng Java RESTful Client với Jersey Client 2.x
• Giới thiệu Swagger – Công cụ document cho RESTfull APIs

Xem thêm các việc làm ngành CNTT hấp dẫn trên TopDev