Bài viết được lược dịch từ: restful.io

Sử dụng API editor nào?

Bạn đang muốn tích hợp các tài liệu hướng dẫn sử dụng API vào trang web của mình? Bạn muốn nhanh chóng đặt một vài endpoint và muốn tạo ra tài liệu hướng dẫn chỉ bằng một cú nhấp chuột?

Bài viết này sẽ đánh một số API editor tốt nhất mà bạn có thể tìm thấy trên mạng. Bạn có thể sử dụng chúng để xây dựng, tạo tài liệu, các enpoint và cho phép các lập trình viên khác tương tác và khám phá các API của mình.

SWAGGER (YAML/JSON)

Tính linh hoạt: 5/5

Tính thân thiện với người dùng: 3/5

Thời gian để học: 1/5

Giới thiệu

Swagger là editor phổ biến nhất, nó sử dụng một ngôn ngữ đánh dấu (markup language) được gọi là YAML. Bạn sẽ cần lưu trữ (host) nó trên server của mình.

Nếu bạn không muốn sử dụng YAML, bạn có thể sử dụng JSON thay thế.

Như hình trên, swagger không chỉ là một editor, nó còn cho phép bạn thử nghiệm API từ trình xem tài liệu mở rộng (external documentation viewer).

Swagger Doc viewer

Ngoài giao diện, trình xem tài liệu (documentation viewer) của swagger khá mạnh mẽ. Nó hỗ trợ nhiều kiểu xác thực khác nhau, endpoint các nhóm tài nguyên, có thể nhanh chóng chỉnh sửa lược đồ (schema) của dữ liệu (payload), dễ dàng hiển thị và thay thế các tham số truy vấn (khi cần).

Kết luận

  • Tính thân thiện người dùng - YAML có thể mất một chút thời gian để học nhưng nó thực sự thân thiện với các lập trình viên. Để viết YAML hoàn hảo bạn có thể phải mất thêm một chút thời gian nữa.
  • Tính linh hoạt - Các thông số được định nghĩa thực sự tốt và đề cập hầu hết những trường hợp sử dụng trong mô hình RESTful APIs. Một kiến trúc sư hoặc nhà thiết kế API sẽ tìm thấy một lượng lớn hướng dẫn trong cộng đồng Swagger trên Github với nhiều thông tin để tạo ra các bản thiết kế REST phù hợp.
  • Thời gian để học - 4h - Phải mất một thời gian để học các sử dụng YAML. Dành một vài giờ để thử API của bạn và tạo ra cái bạn cần. Nhưng khi bạn đã làm chủ được YAML nó sẽ nhanh hơn.

Mashape API Editor

Tính linh hoạt: 5/5

Tính thân thiện với người dùng: 2/5

Thời gian để học: 1/5

Giới thiệu

Khi sử dụng Mashape API editor bạn sẽ có khả năng tạo ra các đoạn code (code snippet) trong ngôn ngữ lập trình ưa thích. Không giống các editor khác, bạn không cần phải học một ngôn ngữ nào cả. Thay vào đó bạn chỉ cần nhấp chuột vào các box để thêm các endpoint, các tham số và các mô hình để tạo ra API của bạn.

Sức mạnh của trình soạn thảo này là tính đơn giản, bạn sẽ không cần đọc hướng dẫn để sử dụng nó.

Mashape có tài liệu hướng dẫn khá rõ ràng cách để thêm một API, chỉ bằng cách làm theo một vài hình ảnh và qua một số bước bất kỳ ai cũng có thể làm chủ được editor này.

Editor này còn hỗ trợ nhiều tính năng khác bao gồm hỗ trợ khác hàng (các nhà cung cấp API), khả năng thêm hóa đơn và kiếm tiền.

Không như Readme.io Mashape hỗ trợ rất nhiều cơ chế phân quyền (authorization) khác nhau: OAuth1 và 2, Basic Auth, Query parameters, Header Authentication.

Mashape là một công cụ tuyệt vời cho các nhà cung cấp API với một lượng nhỏ endpoints muốn quảng bá API của họ tới thị trường hoặc nhúng tài liệu trên trang của họ.

Kết luận

  • Tính thân thiện người dùng - Nó rất trực quan, tuy nhiên một kiến trúc sư khi thêm một lượng lớn các endpoint sẽ cảm thấy hơi bất tiện. Editor trở lên lộn xộn với thông tin và các tác vụ lặp đi lặp lại của việc thêm các endpoint. Ở trường hợp khác, nếu bạn là một người đang tìm hiểu tài liệu hướng dẫn, nó thực sự rất dễ để sử dụng và tạo ra những đoạn code mẫu, cái bạn có thể copy và tải xuống máy tính của bạn.
  • Tính linh hoạt - editor API của Mashape rất linh hoạt, cho phép bất kỳ ai cũng có thể thêm các API. Nó hỗ trợ các header, querystring và nhiều kiểu dữ liệu (playload).
  • Thời gian để học - dưới 1 giờ. Nó thực sự khá đơn giản. Bạn có thể dễ dàng thêm các API. Bạn không cần phải đọc bất cứ thứ gì. Vì thế bạn có thể bỏ qua tài liệu hướng dẫn và tiến hành thêm các endpoint, mô hình.

API Designer Studito (RAML)

Tính linh hoạt: 5/5

Tính thân thiện với người dùng: 2/5

Thời gian học: 1/5

Giới thiệu

Sau khi đăng ký tài khoản, chúng ta có thể xây dựng API với RAML.

Console

API editor này là một ứng dụng web được xây dựng dựa trên RAML, nó là một cách để viết kiến trúc của API. Cả con người và máy tính đều có thể hiểu được RAML. Với những lập trình viên có kinh nghiệm RAML khá dễ hiểu.

RAML khá ngắn gọn. Bạn chỉ cần viết cái mình cần định nghĩa.

Khi bạn đã tạo các thông số kỹ thuật cho API của mình, bạn được yêu cầu thêm một API portal. Đó là nơi bạn có thể giới thiệu API vừa mới tạo với thế giới, thêm giải thích cho người đọc nếu cần.

Tài liệu sau khi thêm một API trong RAML

Kết luận

  • Tính thân thiện với người dùng - Những người mới sử dụng sẽ không tìm thấy bất kỳ hướng dẫn nào về cách bắt đầu với API designer. Nhưng, có rất nhiều tài liệu hướng dẫn về RAML.
  • Tính linh hoạt - RAML editor hỗ trợ toàn bộ ngôn ngữ đánh dấu để định nghĩa mọi thứ trong RESTful API của bạn. Các Endpoint và kiến trúc là an toàn, không có nhiều editor có thể linh hoạt hơn editor này.
  • Thời gian để học - Xấp xỉ 3h. Không tính thời gian để học RAML và các công cụ liên quan. Nó phụ thuộc vào việc bạn hiểu kiến trúc và các thông số kỹ thuật của REST, cách sử dụng mỗi khối phù hợp để biểu diễn API, vì vậy bạn có thể cần nhiều hoặc ít thời gian hơn.

README Editor

Tính linh hoạt: 2/5

Tính thân thiện với người dùng: 4/5

Thời gian để học: 5/5

Giới thiệu

Readme.io là một công cụ để tạo các file README, cho dù bạn muốn tạo F.A.Qs (các câu hỏi thường gặp) hay tài liệu hướng dẫn RESTful API, nó đều có thể đáp ứng. 

Ngoài việc tự xây dựng API, bạn cũng có thể import các tài liệu mà Readme.io hỗ trợ.

Điều đầu tiên mà bạn thấy khi xây dựng tài liệu hướng dẫn với editor này là, không giống các editor trước, người dùng hoàn toàn kiểm soát cách nó sẽ tạo ra tài liệu API.

Editor rất linh hoạt

Sau khi định nghĩa endpoint, phương thức xác thực (tại thời điểm viết bài nó dường như chỉ hỗ trợ duy nhất basic authentication) và các tham số có thể được truyền tới endpoind, người dùng có thể nhận phản hồi như mong đợi hoặc mặc định.

Ngoài ra bạn có thể thêm table, image và inline html.

Thiết kế cực kỳ linh hoạt cho phép tạo và duy trì một danh sách các endpoint, các phương thức http phù hợp và nhóm chúng với nhau một cách thoải mái.

API documentation explorer

Kết luận

  • Tính thân thiện với người dùng - Bằng trực giác bạn có thể sử dụng công cụ này và tạo ra một vài thứ có ý nghĩa. 
  • Tính linh hoạt - Nó là một sản phẩm linh hoạt, bạn có thể viết và giải thích cách tạo các cookie với công cụ này. 
  • Thời gian để học - Dưới 1h - Nó thực sự đơn giản. Không có gì phải học thêm ngoài khả năng di chuyển chuột và nhấn các phím trên bàn phím của bạn.

Apiary API Editor

Tính linh hoạt: 1/5

Tính thân thiện với người dùng: 5/5

Thời gian để học: 1/5

Giới thiệu

Tương tự swagger đây là một editor trên trình duyệt. Các lỗi xuất hiện inline và thực sự diễn giải tốt, vì thế bạn sẽ biết cái cần làm ngay lập tức mà không cần phải tham khảo tài liệu.

Markdown editor để viết các API

Sử dụng API Blueprint (bản thiết kế API) có thể còn tuyệt vời hơn so với sử dụng RAML. Nó thực sự thông minh khi tận dụng sức mạnh của mardown để tạo ra các tài liệu hướng dẫn API.

Nhược điểm duy nhất, có lẽ là nó có nhiều thuật ngữ hơn RAML, nhưng nó thân thiện với những người mới bắt đầu hơn.

API documentation viewer

Documentation viewer (trình xem tài liệu) cung cấp cho người đọc cái nhìn tổng quan và rõ ràng về các endpoint của API, các tham số, các phản hồi (response) cũng như tự động tạo ra code để copy paste tới các ứng dụng để thực thi các request tương tự như khi tạo ra trong trình duyệt. Bằng cách này  bạn có thể nhanh chóng tạo các request tới các API, xác định các đối tượng trả về và tích hợp code vào app chỉ trong vài giây.

Kết luận

  • Tính thân thiện người dùng - Giao diện bóng bẩy, các tính năng được bố trí hợp lý, trải nghiệm người dùng tốt.
  • Tính linh hoạt - Vì cách bạn thêm các tài nguyên là sử dụng một ngôn ngữ (API Blueprint) nên bạn có sự linh hoạt về cách các endpoint được tạo ra. Và mặc dù editor chỉ là một text-editor, nhưng phần hiển thị kết quả là một tài liệu tương tác cho phép những người sử dụng API của bạn thử nghiệm các request và tạo ra các đoạn code snippet.
  • Thời gian để học - 2h - Vì nó là markdown và nếu bạn là một lập trình viên thì bạn có thể học nó nhanh hơn.

Tổng kết

Tất cả các editor đều có ưu và nhược điểm, nếu bạn là một lập trình viên có kinh nghiệm bạn có thể thấy thoải mái khi sử dụng Swagger hoặc API Designer.

Nếu bạn đang tìm kiếm một hướng tiếp cận khác và một thiết kế rõ ràng, bạn nên thử API Blueprint và editor của nó.

Cuối cùng nếu bạn có một công ty tạo ra một API và muốn nhanh chóng giới thiệu tới các lập trình viên khác bạn nên tham khảo Mashape.

Hoặc sử dụng Readme.io nếu cần một editor nhẹ nhàng cho các API cực kỳ đơn giản.

Không có một editor nào thực sự chiến thắng vì nó phụ thuộc vào các yêu cầu của bạn.