OpenAPI cần tạo mẫu đường dẫn đề cập 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 dấ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, OpenAPI 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).
1.3.2 Định nghĩa Swagger là gì?
Swagger là một công cụ có mã nguồn mở và dùng để xây dựng nên OpenAPI Specifications để có thể thiết kế, xây dựng tài liệu và sử dụng REST APIs.
Với các nhà phát triển, khi sử dụng Swagger sẽ được cung cấp 3 tool chính như sau: Tool Swagger Editor: được sử dụng để thiết kế, xây dựng nên các APIs một
cách mới hồn tồn hoặc là có thể edit lại từ những APIs có sẵn với việc tận dụng một file config.
Tool Swagger Codegen: có tác dụng trong việc generate ra code thơng qua sử dụng các file config sẵn có trước đó.
Tool Swagger UI: ứng dụng trong việc generate các file ra HTML, CSS,... xuất phát từ một file config.
Để có thể thực hiện việc viết document cho Swagger thì các developers sẽ có 2 cách để tiếp cận với bộ mã nguồn mở này.
Cách 1: Top down approach: dùng để thiết kế nên các APIs trước khi thực hiện việc code liên quan.
Cách 2: Bottom down approach: dùng để mô tả các vấn đề, thông số liên quan API thông qua việc sử dụng thiết kế có sẵn của file config.
Với những tool được liệt kê ở trên của Swagger thì Swagger UI được biết đến là một tool có sự thơng dụng phổ biến nhất hiện nay. Với tool Swagger UI, tool này có ứng dụng rất lớn trong việc xây dựng giao diện cho các tài liệu bắt nguồn từ file config áp dụng dưới chuẩn Open API. Giao diện được tạo ra bởi tool này thường có tính tường minh và khá rõ ràng, hiện ra một cách cụ thể nhất cho các nhà phát triển. Điều này sẽ giúp ích rất lớn cho cả người dùng lẫn các lập trình viên trong việc đọc hiểu và sử dụng. Thêm vào đó, đây cũng là dẫn chứng cho việc các developers sử dụng file config nhưng lại có sự tách biệt một cách hoàn toàn giữa các tác vụ với nhau.
Mỗi API được sử dụng trong quá trình này sẽ cho chúng ta biết một cách chính xác nhất về nguồn ra một cách chi tiết. Thêm vào đó chính là việc những trường cần phải được gửi lên hệ thống cũng như các trạng thái kết quả có thể được trả về. Điều đặc biệt nhất có lẽ chính là việc ta có thể đưa các dữ liệu vào trong để test thử các kết quả liệu có thực sự chính xác và đảm bảo tính đúng đắn hay không.
1.3.3 Cấu trúc cơ bản của Swagger.
1.3.3.1 Metadata hay Info
Hầu hết, mỗi Open API Specifications được sử dụng đều sẽ bắt đầu với từ khóa “Open API” nhằm mục đích cho việc khai báo tên của phiên bản đó. Với loại phiên bản được sử dụng sẽ có ý nghĩa trong việc định nghĩa lại toàn bộ những cấu trúc ở trong API. Phần Info sẽ có các thơng tin cơ bản về API như title, description và các version. Cụ thể thì:
Title sẽ là tên mà bạn đặt cho API của mình.
Description chính là các thơng tin về API của bạn được đưa ra một cách chi tiết và xuất hiện ở nhiều mặt cụ thể khác nhau. Với việc mơ tả này thì bạn hồn tồn có thể viết thành nhiều dòng nếu như dài quá và sử dụng cú pháp hỗ trợ như markdown.
Version là phiên bản được sử dụng trong quá trình tạo dựng của bạn với API. Metadata hay Info sẽ có chức năng trong việc hỗ trợ đưa ra các từ khóa về các thơng tin liên quan như thông tin liên lạc, thông tin về chứng chỉ, các điều khoản trong việc sử dụng,...
1.3.3.2 Servers
Để có thể test được các API thì bạn cần có một đường dẫn liên quan đến servers. Và đây chính là phần tạo ra một đường dẫn cụ thể của servers được sử dụng để thực hiện chức năng trên. Trong phần này, việc định nghĩa hay là nhiều các servers khác nhau sẽ hoàn toàn tùy thuộc vào quyết định của bạn.
1.3.3.3 Paths
Được biết phần mấu chốt, trọng tâm của API được sử dụng. Với phần này, nhiệm vụ của những nhà lập trình viên chính là định nghĩa những paths xuất hiện trong API hay các phương thức, những tham số cụ thể tồn tại trong API đó.
Một vài lưu ý cần được chú ý như sau:
Việc bắt đầu sẽ cần phải bằng từ khóa “paths”.
Sau đó chính là các phương thức được sử dụng trong API như Get, Post, Delete,...
Phần mơ tả một cách tóm tắt, ngắn gọn của API: Summary.
Những tham số được đưa vào trong API gọi là parameters. Với phần này, lập trình viên có thể thực hiện set các tham số required, thực hiện việc mô tả những tham số đó hoặc là validate cho chúng. Thêm vào đó, điều đặc biệt ở phần này chính là việc bạn có thể chỉ định một model bất kỳ nhằm mục đích định nghĩa cho những tham số đó.
Cuối cùng là phần trả về của server đó hay cịn được biết đến là response. Với phần trả về này thì bạn có thể thực hiện việc định nghĩa cho các HTTP code mà người dùng có thể nhận được như 200, 404,... kèm theo đó là những dịng mơ tả xuất hiện với từng trường hợp cụ thể.
Thêm vào đó, ở phần này, các parameters sẽ sở hữu khá nhiều loại khai báo khác nhau đứng sau từ khóa”in” mà chúng ta đều cần phải lưu ý:
In body: giúp cho người dùng có một khơng gian để tạo ra một dữ liệu đầu vào. Ở khơng gian này, người dùng hồn tồn có thể nhập các dữ liệu về những yêu cầu cơ bản vào trong đó.
In formData: giúp cho người dùng tạo được input đã được xác định trước để có thể thực hiện nhập các dữ liệu yêu cầu theo từng miền đã được định sẵn. In path: sử dụng trong việc tạo lập một input vào trong giá trị để khai báo trong
các routers, thông thường được gọi là ID.
In query: được sử dụng trong việc tạo input nhập vào các giá trị thống kê theo các miền định sẵn để dùng trong việc gửi các query request.
In header: thực hiện dùng để khai báo các giá trị có trong header của yêu cầu mà bạn cần thực hiện truyền tải lên.
1.3.3.4 Schema
Trong hệ thống SQL Server, Schema mới bắt đầu được nhắc đến từ phiên bản 2005. Đó là một khơng gian tên được sử dụng để gom các table vào một nhóm, chúng có tác dụng để quản lý dễ dàng hơn. Nếu bạn khơng dùng Schema trong cơ sở dữ liệu, thì Schema lúc này sẽ được thay thế bởi một mặc định khác, đó là Dbo.
Chẳng hạn như có hai loại table chính trong lược đồ cơ sở dữ liệu như sau: thứ nhất là các table về tin tức, lúc này sẽ đặt tên cho Schema là “news”, trong đó gồm các table có bản chất nội dung là tin tức vào. Thứ hai là các table về hệ thống, lúc này sẽ đặt tên cho Schema là
“sys”, trong đó gồm các table bản chất liên quan đến hệ thống. Trong một cơ sở dữ liệu, tên hay tiêu đề của Schema là duy nhất, chúng được thiết lập với công thức: server.database.schema.object.
Schema được biết đến với cơng dụng hỗ trợ gom các nhóm các table trong cùng một chủ đề, chúng giúp người dùng có thể thuận lợi trong việc quản lý các table. Bên cạnh đó, điều tuyệt vời hơn là người dùng có thể gắn user khác nhau và phân quyền quản lý cho mỗi Schema được tạo.
Nói một cách dễ hiểu và đơn giản nhất thì Schema có thể được định nghĩa như một model. Schema sẽ thực hiện phần khai báo thơng qua việc sử dụng từ khóa component và schemas.
Những vấn đề cần quan tâm trong Schema:
Loại tham số đầu tiên được sử dụng là tên của model hay users.
Sau đó chính là định dạng được sử dụng hay object.
Cuối cùng chính là các thơng tin về thuộc tính.
1.4. Json Web Token (JWT)
1.4.1 JWT là gì?
Json Web Token là một chuỗi mã hóa mà nguồn gốc ban đầu là một chuỗi JSON. Chuỗi thơng tin dạng JSON bằng phương pháp mã hóa nào đó, nó trở thành 1 chuỗi ký tự lộn xộn nhìn vào sẽ rất khó hiểu.
Theo định nghĩa tiêu chuẩn thì JSON Web Token (JWT) là 1 tiêu chuẩn mở (RFC 7519) định nghĩa một cách nhỏ gọn và khép kín để truyền một cách an tồn thơng tin giữa các bên dưới dạng đối tượng JSON. Thơng tin này có thể được xác minh và đáng tin cậy vì nó có chứa chữ ký số. JWTs có thể được ký bằng một thuật tốn bí mật (với thuật tốn HMAC) hoặc một public/private key sử dụng mã hóa RSA.
Như vậy, bảo mật JWT là phương pháp xác thực quyền truy cập (Authentication) bằng JSON Web Token.
1.4.2 Cấu trúc của một JWT
JSON Web ToKen bao gồm 3 phần, được ngăn cách bởi dấu chấm (.) được minh họa trong hình 1.12 :
1. Header 2. Payload