Design API với APIBluePrint
API Design
1
emacs
7
vim
20
Male avatar

kiennq viết ngày 17/06/2018

Chiều Chủ Nhật, chán như con gián.
Muốn test thử cái plugin mình viết mà không có API key, Kipalog đòi hỏi lắm thứ thật.

Chợt nhớ đến bác này Apiary vừa giúp design API, vừa tạo API mock luôn. Chẳng cần API key vẫn test như thường. Design API cho team dùng cứ phải gọi là mượt.
Ta thử tìm hiểu về bác ấy chút nhé.

How Apiary works.

Write an API in 30 minutes. Share it with your teammates or customers. Let them use the API mock to take your API for a spin--without writing any code. Iterate, rinse & repeat. Coding can wait until you know what your developers really need.

Thế là rõ rồi, dùng Apiary ta có thể viết bản nháp cho API, share với team, chờ feedback rồi tiếp tục design tiếp.
Mà chẳng cần viết dòng code nào cả

Về chi tiết thì Apiary dùng APIBluePrint format, nôm na là chả khác gì file markdown cả.
Viết nháp API cho team đọc xong là test thử được luôn, tiện dễ sợ. Cần gì phải mất công sức tạo thử cái server nữa chứ.

Ví dụ luôn, cái này là API của Kipalog

POST /api/v1/post/preview

What: To preview a post at kipalog using kipalog markdown engine
Limit: 100 request / 5 minutes

Request

JSON

{
 "content": "**content of a post (markdown)**",
}
key value description
content required string content of need-rendered post

Response

JSON

{
 "content":"<html></html>",
 "status": 422,
 "cause": "unprocessable entity"
}
key value description
content string rendered html of posted content
status int http status code
cause string failed reason if fail

Chuyển sang apiblueprint format thì nó thành thế này

Preview post [POST /api/v1/post/preview]

What: To preview a post at kipalog using kipalog markdown engine
Limit: 100 request / 5 minutes

  • Request (application/json)

    • Headers

      Accept-Charset: application/json
      X-Kipalog-Token: 50apc5dac3vwjvbrr8631s42j1veif

    • Attributes

      • content: Content of a post (markdown) (string, required) - content of need-rendered post
  • Response 200 (application/json)

    • Attributes
      • content: <html><body>Content of a post (markdown)</body></html> (string) - rendered html of posted content
      • status: 200 (number) - http status code
      • cause: `` (string) - failed reason if fail

Đều là markdown cả, convert 1:1 luôn.

Thế nhưng, apiblueprint có vẻ khó nhìn hơn nhỉ, ko thấy json snippet như trong file markdown bình thường.

Thực ra cái đấy mới là một trong những điểm mạnh của của apiblueprint.
Nếu các bác để ý, trong phiên bản đầu dùng markdown để viết mô tả API, anh @huydx phải thêm một bảng để ghi rõ requirement cho các field trong API đó (required chẳng hạn).

Khi dùng apiblueprint, ta có thể sử dụng MSON để mô tả các tiêu chuẩn đó cho API (string, requiredấy, enum cũng được luôn). Ngắn gọn súc tích nhỉ.

Khi dùng kết hợp với Apiary, thì nó thành thế này https://kipalog.docs.apiary.io/. Các mô tả API cực kì chi tiết, tương tác tung toé tít mù, lại còn có cả snippet để thử nữa chứ, ngọt cả nước lẫn xương luôn :smile:. Các bác cứ nghịch thử nhá.
Snippet đây này

Đặc biệt, Apiary host luôn cả 1 cái Mock sever cho mình http://private-anon-cf5a624b3e-kipalog.apiary-mock.com, cứ thoải mái mà test API thôi chứ nhỉ.
Frontend cứ gọi là quẩy tit mù trong khi backend còn chưa phải code dòng nào nhé.
Chả cần API key vẫn test được như thường.

Tutorial đây luôn nhé
https://apiblueprint.org/documentation/tutorial.html

Bonus các bác luôn cái plugin của APIBluePrint cho Emacs với Vim

;; Emacs
(use-package apib-mode
  :ensure t
  :mode ("\\.apib\\'" . apib-mode)
  :config
  (with-eval-after-load 'evil
    (evil-define-key 'normal apib-mode-map (kbd "SPC a p") #'apib-parse)
    (evil-define-key 'normal apib-mode-map (kbd "SPC a v") #'apib-validate)))
" vim
call dein#add('kylef/apiblueprint.vim', {'on_ft' : ['apiblueprint']})
Bình luận


White
{{ comment.user.name }}
Bỏ hay Hay
{{comment.like_count}}
Male avatar
{{ comment_error }}
Hủy
   

Hiển thị thử

Chỉnh sửa

Male avatar

kiennq

2 bài viết.
12 người follow
Kipalog
{{userFollowed ? 'Following' : 'Follow'}}
Cùng một tác giả
Male avatar
4 3
Giới thiệu luôn cái Emacs plugin cho Kipalog. Post luôn bài từ trong Emacs luôn. (Link) Kipalog's plugin for Emacs Let you write and post to (...
kiennq viết 1 tháng trước
4 3
Bài viết liên quan
White
14 12
Một vài thủ thuật vim mới biết, ghi lại cho khỏi quên Căn lề các cột dữ liệu Để căn lề ấn phím esc (để sang command mode) :%column t Chọn th...
studybot viết 3 năm trước
14 12
{{like_count}}

kipalog

{{ comment_count }}

bình luận

{{liked ? "Đã kipalog" : "Kipalog"}}


Male avatar
{{userFollowed ? 'Following' : 'Follow'}}
2 bài viết.
12 người follow

 Đầu mục bài viết

Vẫn còn nữa! x

Kipalog vẫn còn rất nhiều bài viết hay và chủ đề thú vị chờ bạn khám phá!