Chắc hẳn là lập trình web thì mọi người đã từng một lần kết nối đến một hệ thống khác thông qua Web Service, có thể là SOAP, RESTful…Nội dung bài viết này mình sẽ chia sẻ với mọi người một số vấn đề và giải pháp mà mình đang gặp phải khi triển khai các Restful service.

Restful Documentation

Trong quá trình thiết kế Restful API, documentation (docs) cho API là một trong những thứ cực kỳ cần thiết để giúp bạn cũng như công ty, khách hàng dễ dàng làm việc trên API mà bạn thiết kế.

Docs API đơn giản có thể là các ghi chú, word, excel hoặc các SaaS base service để giúp tạo API nhanh chóng và tiện lợi hơn cũng như hỗ trợ làm việc nhóm hiệu quả hơn.

Đã thử dùng rất nhiều công cụ và nhiều phương tiện khác nhưng không có cái nào phù hợp nhu cầu nên đành tự phát triển một công cụ tạo docs API riêng cho mình, đơn giản và linh hoạt hơn, đó là Apitoy.com.

Cũng như hầu hết các công cụ SaaS based khác để làm Restful API Docs, Apitoy.com cũng cho phép tạo nhiều dự án, mỗi dự án sẽ có nhiều nhóm request (group). Mỗi request sẽ có quy định loại request (GET, POST, PUT..), tham số đầu vào, định dạng cũng như các thông tin request / response của một request.

Một số hình ảnh của Apitoy:

Mock Server

Cũng như các lập trình viên thiết kế Restful API khác, việc dựng một Mock server từ một API Docs là một nhu cầu cực kỳ cần thiết để việc test cũng như tách biệt giữa web service consumer & service producer trong quá trình phát triển ứng dụng. Nhờ có Mock server mà phía frontend có thể có data giả (fake data) nhưng có cấu trúc đúng với cấu trúc của API thiết kế và sẽ không lệ thuộc vào backend phải hoàn thành API trước khi thử.

Apitoy có một tính năng rất thú vị và độc đáo là cho phép tự tạo một mock service dựa vào một request mà bạn đã thiết kế và response data (fake data) sẽ được auto-generate khi có request vào đúng mô tả request của bạn như đúng HTTP Method (GET, POST< PUT…), đúng URL…
Lưu ý là để mock service có thể chạy thì bạn bắt buộc phải tạo ít nhất 1 response cho request. Các snippet động “{{…}}” sẽ được bỏ khi xem docs và được thay thế khi có request để lấy mock data.

Apitoy hỗ trợ một số hình thức generate dữ liệu động sau:

Kiểu dữ liệu chuẩn

Nếu các giá trị có dạng “Integer”, “Float”, “String” thì sẽ được thay thế bằng các dữ liệu ngẫu nhiên tương ứng với kiếu giá trị như “100”, “3.14”, “Hello world”…

Faker Snippet

Apitoy có tích hợp thư viện https://github.com/fzaninotto/Faker để giúp bạn generate các dữ liệu ngẫu nhiên trông “thật” hơn ví dụ:

String{{phoneNumber}}: Thay thế bằng số điện thoại ngẫu nhiên
String{{email}}: thay thế bằng email ngẫu nhiên
Integer{{randomNumber}}: thay thế bằng một số ngẫu nhiên
Integer{{randomNumber:5}}: thay thế bằng một số ngẫu nhiên có 5 chữ số
…
Bạn có thể tham khảo website https://github.com/fzaninotto/Faker để biết tất cả các Snippet hỗ trợ trong Apitoy để generate các dữ liệu “giống thật” hơn.

Apitoy Snippet

Bên cạnh các snippet hỗ trợ từ thư viên Faker, apitoy còn cung cấp 2 snippet khác là “enum” và “repeat”.

– String{{enum:option1:option2:option3}}: chọn ngẫu nhiên một giá trị trong danh sách option. Ví dụ: Integer{{enum:0:1}}, String{{enum:”Yes”:”No”}}…

– {{repeat:repeat_id:repeat_count:repeat_seperator}}…{{/repeat:repeat_id}}: lặp lại một đoạn code được đánh dấu. Trong đó: “repeat_id” để đánh dấu đoạn code cần lặp, không có 2 đoạn repeat có cùng “repeat_id”. “repeat_count” số lần lặp lại của đoạn code bạn đánh dấu. “repeat_separator” ký tự phân cách giữa các lần lặp, mặc định là dấu phẩy “,”.

Ví dụ một đoạn code có đánh dấu cho Mock service:

{
    "total": Integer,
    "items": [
        {{repeat:item:2}}
        {
            "id": Integer{{randomNumber:5}},
            "internalid": String{{uuid}},
            "jobtitle": String{{sentence:3}},
            "phone": [
                {{repeat:phone:2}} String{{phoneNumber}} {{/repeat:phone}}
            ],
            "address": String{{streetAddress}},
            "isdeleted": Integer{{enum:0:1}},
            "datecreated": Integer{{unixTime}},
        }
        {{/repeat:item}}
    ]
}

Khi có request vào, server sẽ trả về dữ liệu sau:

{
    "total": 2834983,
    "items": [

        {
            "id": 86279,
            "internalid": "fa25b791-e185-37c1-8830-37ad177e6832",
            "jobtitle": "Nisi architecto laudantium aperiam.",
            "phone": [
                 "499.613.9008" , "(616)119-4152x20704" 
            ],
            "address": "730 Alene Wall",
            "isdeleted": 1,
            "datecreated": 264592903,
        }
        ,
        {
            "id": 90095,
            "internalid": "140abd91-3aba-3562-9dc1-d8f9ce275444",
            "jobtitle": "Tempore et ad quisquam.",
            "phone": [
                 "1-275-835-9601x690" , "05349335502" 
            ],
            "address": "796 Hauck Garden Suite 358",
            "isdeleted": 0,
            "datecreated": 364877373,
        }

    ]
}

——

Hy vọng bài viết này sẽ giúp các bạn có cái nhìn chi tiết hơn về cách triển khai một hệ thống Restful API.