Chắc hẳn tất cả các bạn ai cũng đã từng làm việc với RESTful Web Service nhưng có lẽ không nhiều bạn nghe nói về RAML (RESTful API Modeling Language), một đặc tả giúp chúng ta định nghĩa API specs cho RESTful Web Service. Trong bài viết này, chúng ta hãy cùng nhau tìm hiểu về nó, để biết nó là gì và nó làm được gì cho chúng ta, các bạn nhé!

Đầu tiên, như mình nói, chúng ta sử dụng RAML để định nghĩa API specs cho RESTful Web Service, mục đích của nó để làm gì, có bao nhiêu request URL (hay còn gọi là resource) chúng ta cần implement, chúng sử dụng những HTTP method nào, request parameter của chúng là gì, response body của chúng như thế nào và chúng ta có thể thêm một số ví dụ về request parameter, response body cho các resource đó nữa.

Chúng ta định nghĩa các đặc tả của RAML trong một tập tin .raml. Bây giờ, mình sẽ lấy một ví dụ về nội dung của một tập tin .raml như sau:

Đây là một tập tin .raml định nghĩa API specs cho một hệ thống quản lý sinh viên, bao gồm lấy thông tin của tất cả các sinh viên, lấy thông tin sinh viên bằng id và xoá thông tin sinh viên bằng id.

Ở trên đầu tập tin này, các bạn có thể thấy chúng ta có một số dòng để mô tả về API specs của chúng ta, sử dụng đặc tả RAML phiên bản nào, baseUri là gì, dùng để làm gì và version bao nhiêu:

Như các bạn thấy, title dùng để định nghĩa mục đích của API specs của chúng ta, trong ví dụ này là dùng để quản lý thông tin sinh viên. baseUri dùng để định nghĩa root URL cho các resource, version ở đây là version của API specs nha các bạn. Từ những thông tin này, các bạn có thể có cái nhìn tổng quan về API specs của chúng ta phải không?

Phần còn lại của tập tin .raml là phần định nghĩa chi tiết về các resource trong API specs của chúng ta.

Các bạn có thể thấy, các resource được định nghĩa với cấu trúc cây thư mục.

Các request URL sẽ được bắt đầu với ký tự “/” và nếu một trong số chúng bắt đầu với giá trị giống nhau thì chúng ta có thể kế thừa giá trị giống nhau đó để định nghĩa các request URL. Trong ví dụ trên, mình đã định nghĩa 3 request URL đó là:

• /students với GET HTTP method
• /students/{id} với GET HTTP method
• /students/{id} với DELETE HTTP method

Các request URL này đều bắt đầu với “/students” nên chúng ta có thể kế thừa giá trị này, không cần phải khai báo riêng lẻ.

Request đầu tiên, chúng ta định nghĩa request lấy thông tin tất cả sinh viên.

Đây là một GET request, RAML hỗ trợ cho chúng ta có thể định nghĩa tất cả HTTP method như GET, POST, DELETE, PUT,…

Ứng với mỗi HTTP method, chúng ta có thể định nghĩa kiểu dữ liệu trả về cho mỗi HTTP status code.

Như ví dụ trên, ứng với mỗi request URL, với status trả về là 200, mình đã định nghĩa response body cho mỗi request dưới dạng application/json.

Các bạn có thể định nghĩa response body tuỳ theo response status code mà các bạn muốn, các bạn nhé!

Chúng ta có thể thêm một số ví dụ về response body cho mỗi request URL dưới dạng chuỗi JSON.

Trong request URL thứ hai và thứ ba, mình đã định nghĩa một URI parameter tên là id. Với URI parameter id này, mình sẽ có một section bên dưới request URL để mô tả về nó:

Ở đây, mình đã mô tả URI parameter là id của sinh viên, kiểu dữ liệu là string và một ví dụ về giá trị của nó. URI parameter này có thể dùng chung cho 2 request URL này!

Ngoài kiểu dữ liệu string, RAML còn cho phép chúng ta định nghĩa kiểu dữ liệu object, integer và cả một số kiểu dữ liệu khác nữa. Các bạn có thể tham khảo thêm bài viết Data types trong RAML.

Việc cấu trúc định nghĩa các request URL của RAML giúp chúng ta có thể hình dung rất rõ ràng về API specs phải không các bạn?