Api documentation slate hướng dẫn

In this article, we'll cover what an API is, how to use an API key to grant access to your Mailchimp account, and where to go for support with any additional questions that you may have about the Mailchimp Marketing API.

What is an API?

API stands for application programming interface. It can be helpful to think of the API as a way for different apps to talk to one another. For many users, the main interaction with the API will be through API keys, which allow other apps to access your account without you giving out your password.

Find or generate your API key

If you want to set up an integration with your Mailchimp account, chances are high that you'll need to generate an API key. Users with Manager permissions can generate and view their own API keys. Users with Admin permissions can also see API keys for other account users.

1. Click this link to navigate to the API Keys section of your Mailchimp account: Your API Keys
2. Copy an existing API key or click the Create A Key button.
3. Name your key descriptively, so you know what application uses that key.

Disable an API key

If you're worried that an API key has been compromised, or you no longer use the integration that was accessing your account through a particular API key, you can disable that API key. To disable the API key, follow these steps.

1. Click to open the API Keys section of your account.
2. Find the API key you want to disable, and toggle the slider in the Status column for that API key.
   
   
3. In the pop-up modal, click Disable.
   

API key security

API keys grant full access to your Mailchimp account and should be protected the same way you would protect your password. In particular, there are a few common scenarios to keep in mind when working with API keys.

• Give each integration its own API key, and assign labels to each key so you know which key goes with which application. If a specific API key is compromised, you can disable that key without disabling access to all of your other integrations.
• Be careful not to expose the key to the public (such as in screenshots, videos, or help documentation). Remember that blurring your data isn't always enough. It's best to use "cut" functions in your graphics program to remove the data completely.
• Because of the potential security risks associated with exposing account API keys, Mailchimp does not support client-side implementation of our API using CORS requests or including API keys in mobile apps.
• If a key needs to be shared, generate a new key and label it accordingly so it can be disabled, if needed. Never email the API key, because it would allow access to your Mailchimp account if hackers were to compromise your email account.
• If you revoke a user's access to your Mailchimp account, any API keys created by the user will be removed from your account.
• Access to each endpoint is determined by the role of the user who generated the API key. To learn more about user level permissions, visit Manage User Levels in Your Account.

API support

Our Mailchimp Support Team isn't trained at in-depth API troubleshooting. If you need a developer to help you configure something using the API, check out our great Experts Directory, which lists third-party Mailchimp experts who can be hired to help out.

If you're a developer who wants to build your own integration with Mailchimp, check out our API documentation.

Hiện nay, các ứng dụng viết theo mô hình RESTful API và Software-as-a-Service (SaaS) ngày càng bùng nổ. Thế nên việc có 1 trang quản lý các api của mình một cách đẹp đẽ, khoa học là 1 điểm cộng vô cùng lớn, bởi vì hầu hết các developers đều nhìn vào trang này trước khi nhìn xem code có tốt hay không. Vậy nên trong bài viết của mình sẽ hướng dẫn việc tạo nên 1 trang quản lý document cho API bằng 2 công cụ là Swagger và Slate

Swagger:

Swagger là một công cụ open source khá đơn giản nhưng lại vô cùng mạnh mẽ. Swagger cung cấp 3 tools chính cho các developers :

• Swagger-Editor : dùng để design lên các APIs hoàn toàn mới hoặc edit lại các APIs có sẵn thông qua 1 file config
• Swagger-Codegen : dùng để generate ra code từ các file config có sẵn
• Swagger-UI : dùng để generate ra file html,css,... từ 1 file config

Do cung cấp các tool khá đa dạng nên việc viết document bằng swagger cũng có 2 cách tiếp cận:

• Top-down approach: Nghĩa là chúng ta sẽ design lên các api trước khi viết code
• Bottom-up approach: Nghĩa là từ các api có sẵn sẽ generate ra 1 file config

Slate:

Slate là một công cụ open source, nhiệm vụ chính (và duy nhất) của slate là generate ra các file html,css,... từ 1 file config .md . Ưu điểm của slate là UI cực kì đẹp và khoa học

Ngoài ra, vì chỉ cần config trên 1 file .md nên việc chỉnh sửa nội dung là hết sức đơn giản . Không những thế slate còn support syntax cho hơn 100 ngôn ngữ khác nhau nên việc viết example code cho api của mình không còn là vấn đề phải suy nghĩ tới

Vậy tại sao lại phải dùng Swagger + Slate

Như các bạn có thể thấy, ưu điểm của Swagger là việc chúng ta có thể generate ra 1 file config (ở đây là .json và .yaml) từ chính code của chương trình . Tất nhiên để có thể generate ra thì code phải tuân theo quy ước của ngôn ngữ đó. Ở bài viết mình dùng Golang làm ngôn ngữ, các bạn có thể xem quy ước của Golang tại đây. Thế nhưng phần UI của swagger lại khá rườm rà không đẹp như slate. Ngược lại, UI của slate rất đẹp nhưng lại không thể generate ra file config như swagger

Vậy nên, những việc chúng ta sẽ làm là sẽ từ 1 file config.yaml của Swagger sẽ convert sang 1 file config.md và dùng Slate để generate ra các file html,css,... để publish ra bên ngoài

Các bước thực hiện

1) Chuẩn bị file config.yaml

Ở đây để cho đơn giản mình sẽ sử dụng file example của swagger, các bạn có thể tìm thấy các file tương tự tại đây

Các bạn chọn tab File và download file petstore_simple.yaml:

Ở bước này nếu bạn muốn sử dụng Swagger UI để publish trang document của mình thì các bạn có thể xem hướng dẫn khá chi tiết tại trang này

Trang nó sẽ ra như thế này:

2) Cài đặt tool swagger2slate

swagger2slate là 1 tool giúp chúng ta convert file có định dạng .json và .yaml của swagger thành 1 file .md của slate. Tất cả những gì chúng ta cần làm là download swagger2slate.phar và cấp quyền execute cho file này

chmod +x swagger2slate.phar
echo -e "\nswagger2slate.phar" >> .gitignore

Sau đó tiến hành convert file petstore_simple.yaml thành file có định dạng .md bằng lệnh

./swagger2slate.phar convert ../{your-repository}/petstore_simple.yaml  -o petstore_simple.md

• Note: Vì 1 lý do vô hình nào đó, swagger2slate chỉ support .json và .yml chứ không phải là .yaml nên chúng ta sẽ tiến hành đổi tên file trước khi thực hiện lệnh convert

mv petstore_simple.yaml petstore_simple.yml

Sau khi thực hiện xong lệnh convert, chúng ta sẽ được 1 file petstore_simple.md. Tiếp theo chúng ta sẽ tiến hành cài đặt slate

3) Cài đặt Slate

Chuẩn bị :

• Linux or OS X
• Ruby, version 2.2.5 trở lên
• Bundler gem install bundler

Bắt đầu cài đặt Slate thôi

1) Fork repository của slate về trang github của mình
2) Clone về máy local
3) cd tới directory slate

Lúc này directory slate của mình sẽ có dạng như sau

Trong đó:

• directory source sẽ là file chúng ta sẽ thao tác
• file index.html.md sẽ là file .md để generate ra các file html,css,...
• directory includes là nơi chứa những api nhỏ hơn được tách từ file index.html.md nếu bạn muốn tách ra thành các file .md nhỏ hơn
• Các directory còn lại là các css,logo,.. mặc định của slate, bạn có thể thay đổi các directory này để override các giá trị mặc định của slate

Okay, giờ chúng ta tiến hành copy file petstore_simple.md vào file index.html.md

cp petstore_simple.yaml  ../{your-slate-directory}/source/index.html.md

Bạn có thể xem hình hài trang web trước khi deploy bằng lệnh:

bundle exec middleman server

Sau đó mở trình duyệt đến http://localhost:4567 để xem trang mình đã tạo ra. Nếu tất cả đã hoàn thiện bạn bấm lệnh sau để tiến hành build:

bundle exec middleman build 

Kết quả sau khi chạy hàm đó sẽ như thế này:

Lệnh này sẽ tạo ra 1 directory build chứa file html và cái css bạn chỉ cần deploy directory này lên server của bạn.

Okay, xem trang của mình đã tạo ra xem nào:

Cài đặt languages tab trong slate

1 trong các tính năng mình thích của slate là việc tạo các languages tab cho example code vô cùng đơn giản và bản thân slate cũng support syntax cho khá nhiều ngôn ngữ.

Để thêm tính năng này vào trang của mình, các bạn mở file index.html.md trong directory source của slate và thêm các dòng này vào đầu file

language_tabs:
    -- go
    -- shell

Ở đây mình làm example code trên 2 ngôn ngữ là go và shell, tiếp theo khi viết example code các bạn chỉ cần viết như này:

hoặc như này:

Lời kết

Vậy là chúng ta đã hoàn thành xong việc viết 1 trang document cho RESTful API bằng việc sử dụng Swagger và Slate. Trong phạm vi bài viết, vì kinh nghiệm bản thân còn hạn chế nên việc sử dụng 2 tools trên còn ở mức khá đơn giản, chưa khai thác hết khả năng của cả 2 vậy nên nếu các bạn có kinh nghiệm nào trong việc sử dụng kết hợp 2 tools trên thì có thể đóng góp cho mình và các bạn khác bằng cách comment bên dưới :)