Bài viết được sự cho phép của tác giả Nguyễn Hữu Khanh
Trong bài viết trước, mình đã giới thiệu với các bạn về RAML để định nghĩa API spec. Trong bài viết này, mình sẽ hướng dẫn các bạn chi tiết hơn cách định nghĩa request URL với RAML như thế nào các bạn nhé!
Xem thêm các việc làm Linux hấp dẫn trên TopDev
Để làm ví dụ cho bài viết này, đầu tiên, mình sẽ tạo mới một tập tin .raml với thông tin về API quản lý sinh viên bao gồm thêm, xoá, sửa, tìm kiếm với nội dung ban đầu như sau:
#%RAML 1.0
baseUri: https://localhost:8081/api
title: Student Management System
version: 1.0
Chúng ta sẽ định nghĩa một số request như sau:
- GET /students để lấy danh sách sinh viên
- POST /students để thêm mới sinh viên
- PUT /students/{id} để cập nhập một sinh viên với id được truyền trong request
- DELETE /students/{id} để xoá một sinh viên với id được truyền trong request
- GET /students/find-by-name?name=<student-name>
- GET /students/find-by-ids?id=<id1>,<id2>
Với những request như trên, các bạn có thể định nghĩa một root request “/students” như sau:
/students:
Các bạn cứ hình dung một request URL sẽ chia thành nhiều cấp từ trái sang phải. Ví dụ như request /api/students/find sẽ có 3 cấp là api rồi đến students rồi đến find. Các cấp này ngăn cách bởi dấu “/”. Mỗi cấp sẽ là một level trong tập tin .raml theo thứ tự đó nên trong ví dụ trên của mình, root request cho tất cả các request sẽ là “/students”.
Cho root request này, chúng ta có 2 request là GET và POST để lấy thông tin tất cả sinh viên và thêm mới sinh viên, nên các bạn chỉ cần khai báo những request này như sau:
/students:
get:
post:
Các bạn có thể thêm description cho mỗi request nếu muốn, ví dụ như:
/students:
get:
description: Get all students
post:
description: Add new student
Tiếp theo, chúng ta có 2 request với /students/{id} với PUT và DELETE HTTP method, dùng để cập nhập và xoá thông tin của một sinh viên nào đó. Vì chúng ta đã định nghĩa root request với “/students” rồi nên giờ các bạn chỉ cần định nghĩa cho 2 request mới này như sau:
/students:
get:
post:
/{id}:
put:
description: Update information for a student
delete:
description: Delete information of a student
Các bạn có thể định nghĩa thêm thông tin của các path parameter, thông tin về mục đích của path parameter, kiểu dữ liệu là gì, example về giá trị của chúng nữa. Để làm được điều này, chúng ta sẽ dùng section uriParameters. Ví dụ mình có thể định nghĩa thông tin cho path parameter {id} trong ví dụ trên như sau:
/students:
get:
description: Get all students
post:
description: Add new student
/{id}:
uriParameters:
id:
description: Id of the student
type: string
example: "1"
put:
description: Update information for a student
delete:
description: Delete information of a student
Đối với request /students/find-by-name?name=<student-name>, chúng ta cần định nghĩa thêm section /find-by-name với root request là “/students” như sau:
/students:
get:
description: Get all students
post:
description: Add new student
/{id}:
uriParameters:
id:
description: Id of the student
type: string
example: "1"
put:
description: Update information for a student
delete:
description: Delete information of a student
/find-by-name:
get:
description: Find student by name
HTTP method của request này là GET và mình cũng đã thêm description cho request này.
Đối với request /students/find-by-name này, chúng ta có thêm request parameter tên là name. Chúng ta có thể định nghĩa thông tin request parameter này như sau:
/students:
get:
description: Get all students
post:
description: Add new student
/{id}:
uriParameters:
id:
description: Id of the student
type: string
example: "1"
put:
description: Update information for a student
delete:
description: Delete information of a student
/find-by-name:
get:
description: Find student by name
queryParameters:
name:
description: Name of student
type: string
example: "Khanh"
Như các bạn thấy, mình sử dụng section queryParameters để định thông tin cho tất cả các request parameter của request. Request parameter trong ví dụ này của mình có kiểu dữ liệu String. Các bạn có thể định nghĩa request parameter này có bắt buộc hay không sử dụng thuộc tính “required: false” hoặc sử dụng question mark như sau:
queryParameters:
name?:
description: Name of student
type: string
example: "Khanh"
Trong ví dụ của mình thì request parameter name là bắt buộc các bạn nhé!
Đối với những request có matrix parameter như /students/find-by-ids?id=<id1>,<id2> thì các bạn có thể định nghĩa matrix parameter đó với type là array. Ví dụ như sau:
/students:
get:
description: Get all students
post:
description: Add new student
/{id}:
uriParameters:
id:
description: Id of the Student
type: string
example: "1"
put:
description: Update information for a student
delete:
description: Delete information of a student
/find-by-name:
get:
description: Find student by name
queryParameters:
name:
description: Name of student
type: string
example: "Khanh"
/find-by-ids:
get:
description: Find list of students by a list of Ids
queryParameters:
ids:
description: List of Ids
type: number[]
example: "1,2,3"
Toàn bộ nội dung của tập tin .raml của ví dụ trong bài viết này như sau:
#%RAML 1.0
baseUri: https://localhost:8081/api
title: Student Management System
version: 1.0
/students:
get:
description: Get all students
post:
description: Add new student
/{id}:
uriParameters:
id:
description: Id of the Student
type: string
example: "1"
put:
description: Update information for a student
delete:
description: Delete information of a student
/find-by-name:
get:
description: Find student by name
queryParameters:
name:
description: Name of student
type: string
example: "Khanh"
/find-by-ids:
get:
description: Find list of students by list of Ids
queryParameters:
ids:
description: List of Ids
type: number[]
example: "1,2,3"