Tài Liệu Api - Mẹo Dành Cho An Toàn
Nhân tiện dự án mình đang cải tiến và phát triển API, ngoài coding ra đang dần support quý khách phần tạo tài liệu, từ bây giờ mình mạo muội khám phá một ít tư tưởng về API, API document, Swagger, Basic Structure...tổng thích hợp trong nội dung bài viết này. Hy vọng những tin tức cơ bản dưới phía trên sẽ hữu dụng cho các bạn newbie như bản thân
Để dễ hiểu, hãy đem một ví dụ không còn xa lạ sau.
Bạn đang xem: Tài liệu api
Hãy tượng tưởng, vào một bên hàng, bạn là quý khách và khu nhà bếp là “hệ thống” chuẩn bị thực đối kháng cho bạn. Cái không đủ ở đây là liên kết đặc biệt để truyền đạt yêu cầu của người sử dụng tới khu nhà bếp và chuyển món ăn tới bàn mang lại họ. Liên kết đặc biệt này đó là bồi bàn hoặc API. Bạn bồi bàn - API là tín đồ đưa tin, vẫn nhận yêu thương cầu hotline món cùng truyền đạt lại tới khu nhà bếp - hệ thống. Sau thời điểm thức ăn đã sẵn sàng, bồi bàn sẽ đưa nó tới khách hàng hàng.
API và các loại tài liệu
API Documentation
API Document là tài liệu phía dẫn tham khảo cho API - Giúp người tiêu dùng API biết cách sử dụng API hiệu quả. Tài liệu API thường dành cho các lập trình sẵn viên, góp lập trình viên hoàn toàn có thể đọc cùng hiểu; do đó việc tạo nên một tài liệu API có thiết kế tốt, trọn vẹn và dễ dàng theo dõi là cực kì quan trọng.
API Document bao gồm các hướng dẫn về cách sử dụng tác dụng và tích phù hợp với một API. Nó là 1 tài liệu ngắn gọn, chứa tất cả các tin tức được yêu thương cầu để triển khai việc với API, với thông tin chi tiết về những function (hàm), class (lớp), return type (kiểu tài liệu trả về), những argument (tham số),... được cung cấp bởi các bài gợi ý và ví dụ.
Tài liệu lý giải API Document thường xuyên được thực hiện bằng phương pháp sử dụng các công vậy tạo, gia hạn nội dung cùng trình soạn thảo văn bản thông thường. Những định dạng bộc lộ API hệt như Open
API/Swagger Specification sẽ tự động hóa quy trình xử lý tài liệu, giúp những nhóm dễ ợt hơn trong câu hỏi tạo và gia hạn chúng.
Vậy thay nào là một tài liệu API tốt?
Một tư liệu API tốt được reviews trên tương đối nhiều khía cạnh, khó hoàn toàn có thể liệt kê hết ở đây. Tuy vậy một điều chắc hẳn rằng rằng, tài liệu API chỉ được coi là tốt lúc nó bao gồm cả phía dẫn nhanh và phía dẫn chi tiết; ko kể ra, bắt buộc là tài liệu gồm tính hệ trọng cao để lập trình viên rất có thể kiểm thử những lệnh hotline API.
Tài liệu API cần cung cấp ví dụ về đông đảo lệnh gọi, các tham số số cùng phản hồi cho từng lệnh gọi. Nó phải bao gồm sample source code cho những ngôn ngữ được sử dụng thông dụng như Java, Java
Script, PHP cùng Python. Đồng thời, tư liệu phải cung cấp giải thích đến từng API request và các ví dụ về message lỗi.
API Specification
API specification là 1 thuật ngữ thường xuyên được sử dụng thay thế lẫn nhau cùng với API definition. Tuy vậy hai thuật ngữ này có nhiều điểm tương đương nhưng thực tế chúng là các thực thể không giống nhau.
API specification cung cấp sự đọc biết rộng rãi về giải pháp một API vận động và cách API link với các API khác. Nó giải thích cách hoạt động vui chơi của API và tác dụng mong ngóng khi thực hiện API.
Tài liệu sệt tả API bao gồm nhiều đối tượng người tiêu dùng API, giá trị và tham số, bí quyết các đối tượng người dùng được điện thoại tư vấn và tính năng của từng đối tượng. Ngoại trừ ra, tài liệu đặc tả API cũng cho biết thêm các mối quan hệ giữa các đối tượng và cách mỗi đối tượng hoàn toàn có thể được sử dụng.
API Definition
API definition tương tự như như API specification ở vị trí nó hỗ trợ sự đọc biết về phong thái một API được tổ chức và giải pháp API hoạt động. Tuy nhiên, API definition đào bới việc áp dụng API của đồ vật thay vị việc áp dụng API của con tín đồ - các lập trình viên.
Tài liệu khái niệm API đưa tin về cách thức buổi giao lưu của API, bí quyết nó link với các API không giống và công dụng mong đợi ở định dạng cơ mà máy móc thiết bị hoàn toàn có thể đọc được. Nó triệu tập vào việc định nghĩa API cùng phác thảo cấu tạo của API.
Tài liệu này được áp dụng làm cơ sở cho những công cụ auto như auto tạo tài liệu API (Swagger
Hub với Swagger Inspector), code samples với SDK (REST United và Swagger
Hub).
Sự khác biệt giữa API Documentation, Specification, cùng Definition
Tài liệu API, quánh tả API và định nghĩa API đều có liên quan tiền với nhau, nhưng bọn chúng là các thực thể khác nhau. Cùng mỗi nhiều loại tài liệu đều ship hàng một mục đích đặc biệt quan trọng khác nhau.
Tài liệu API cho những nhà trở nên tân tiến và những người sử dụng API khác biết cách sử dụng API.
Tài liệu quánh tả API cung cấp sự hiểu biết rộng thoải mái về chức năng của API và hiệu quả mong đợi. Đặc điểm kỹ thuật đa số là về kiến thiết của API hoặc triết lý của API. Kiến tạo và chức năng của API là những yếu tố chính khi lựa chọn tích hòa hợp API với một ứng dụng.
Và cuối cùng, tài liệu quan niệm API hướng đến việc thực hiện API của thiết bị máy móc, cung cấp định dạng mà thiết bị đó hoàn toàn có thể đọc được để sử dụng bởi các công cụ tự động hóa như tài liệu API tự động hóa (automatic API documentation) và trình tạo thành SDK tự động hóa (SDK generators).
Hiểu sâu rộng về API Document
Tầm quan trọng đặc biệt của API Document
Một điều thú vị là những lập trình viên thường ít chú ý đến tài liệu giải đáp (API document) khi chạy code. Trên thực tế, việc tiến hành code còn dễ dàng hơn tương đối nhiều so với câu hỏi viết một tài liệu API tốt.
API document tác động trực tiếp tới vấn đề tích thích hợp và thực hiện API. Thành phầm của bạn có thể có tính năng tốt nhất, nhưng mà sẽ không người nào dùng trường hợp họ không biết phương pháp sử dụng như thế nào.
Có thể nói, API document là nền tảng giúp lập trình viên có trải nghiệm tốt.
Swagger là gì?
Swagger là một tool có thể chấp nhận được mô tả cấu trúc của những API để máy móc có thể đọc chúng. Bằng cách đọc cấu trúc API, Swagger tất cả thể auto tạo ra một tư liệu API đẹp và bao gồm tính tương tác.
Ngoài ra, Swagger cũng đều có thể tự động tạo ra thư viện khách hàng cũng tương tự kiểm tra tự động hóa (automated testing) bằng phương pháp yêu mong API trả lại một YAML hoặc JSON cất mô tả chi tiết về toàn cục API. Tệp này về cơ phiên bản là một list tài nguyên API tuân theo điểm lưu ý kỹ thuật Open
API, vào đó bao hàm các tin tức như:
API có những tham số nào? Trả về đều gì?
API bao gồm cần authorization như thế nào không?
Điều khoản, thông tin tương tác và giấy phép áp dụng API
Có thể chế tác Swagger specs theo cách thủ công bằng tay hoặc tạo auto từ những chú thích trong mã nguồn. Kiểm soát swagger.io/open-source-integrations để ráng được danh sách những công cụ cho phép tạo Swagger trường đoản cú code.
Cấu trúc cơ bạn dạng của Swagger Specs
Định nghĩa Swagger hoàn toàn có thể được viết bởi JSON hoặc YAML. Phần dưới đây sẽ lấy những ví dụ về YAML, tương tự như cho JSON.
Một Swagger specification mẫu viết bởi YAML đã như sau:
Metadata
Mọi thông số kỹ thuật kỹ thuật của Swagger đều bắt đầu với phiên phiên bản Swagger, trong các số ấy 2.0 là phiên bản mới nhất.
Phiên bản Swagger xác định cấu tạo tổng thể của thông số kỹ thuật kỹ thuật API - bao gồm những ngôn từ gì với mô tả những nội dung kia ra sao.
Sau đó, nên chỉ định API info (thông tin API), tất cả title (tiêu đề), description (mô tả tùy chọn) và version (phiên bản API, chưa hẳn phiên bạn dạng Swagger).
version có thể là một chuỗi ngẫu nhiên. Bạn cũng có thể sử dụng major.minor.patch hoặc định hình tùy ý như 1.0-beta hoặc 2016.11.15.
descriptioncó thể đa cái và cung ứng Git
Hub Flavored Markdown để trình bày văn phiên bản đa dạng thức.
info cũng cung cấp các ngôn từ khác như tin tức liên hệ, giấy phép...
Base URL
Base URL cho toàn bộ các lệnh gọi API hầu như sử dụngschemes,host và base
Path.
Mỗi một đường dẫn API (API path) đều tương quan đến base URL, ví dụ /users thực chất đó là https://api.example.com/v1/users.
Consumes, Produces
Consumes với Produces khẳng định các một số loại Mi
ME được API hỗ trợ.
Xem thêm: Hình Thức Kế Toán Chứng Từ Số, Trường Hợp Nào Doanh Nghiệp Cần Lập Chứng Từ
Paths
Phầnpaths xác minh các endpoint (thao tác) bơ vơ trong API và những phương thức HTTP được hỗ trợ bởi những endpoint này.
Ví dụ, GET /users hoàn toàn có thể được miêu tả như sau:
Parameters
Các thao tác có thể có các tham số được pass qua đường dẫn URL(/users/user
Id), chuỗi truy nã vấn (/users?role=admin), tiêu đề (X-Custom
Header: Value) và nội dung yêu cầu.
Responses
Đối với mỗi thao tác, bạn có thể xác định các mã trạng thái rất có thể có, chẳng hạn như 200 OK hoặc 404 Not Found cùng schema của câu chữ phản hồi.
Lược đồ hoàn toàn có thể được khẳng định inline (nội tuyến) hoặc tham chiếu trường đoản cú định nghĩa bên ngoài thông qua $ref. Quanh đó ra, chúng ta cũng có thể cung cấp các phản hồi mẫu mã (example responses) mang lại từng các loại nội dung.
Input & Output
Phần definitions cho phép định nghĩa cấu trúc dữ liệu chung được sử dụng trong API. Kết cấu dữ liệu này có thể được tham chiếu trải qua $ref bất cứ lúc nào cần schema cho tất cả nội dung yêu mong (request body) với nội dung bình luận (response body).
Ví dụ, với đối tượng người tiêu dùng JSON này:
có thể được biểu diễn dưới sạng sau:
Và tiếp nối được tham chiếu vào request body toàn thân schema, response body schema như sau:
Authentication
Từ khóa security
Definitions cùng security dùng để làm mô tả các cách thức xác thực được áp dụng trong API.
Automation có một vị trí đặc trưng trong quả đât công nghệ. Rộng nữa, bây giờ Agile development đã có chỗ đứng bền vững và kiên cố trong ngành công nghiệp phần mềm. Đã bao gồm một sự chuyển đổi đáng chăm chú trong cách chúng ta phát triển những kịch phiên bản test tự động hoá vào agile. Kéo theo đó, nhu cầu kiểm demo API cũng tăng lên.
1. API là gì?
Về mặt kỹ thuật, API là viết tắt của hình ảnh lập trình áp dụng (Application Programming Interface).
API là thủ tục trung gian kết nối những ứng dụng cùng thư viện khác nhau.
Nó cung cấp khả năng truy xuất đến một tập các hàm xuất xắc dùng, trường đoản cú đó hoàn toàn có thể trao đổi tài liệu giữa các ứng dụng.
API rất có thể sử dụng cho web-based system, operating system, database system, computer hardware, or software library.
API specification tất cả thể có khá nhiều dạng, nhưng thường bao gồm các đặc tả mang lại routines, data structures, object classes, variables, or remote calls. POSIX, API Windows với ASPI là rất nhiều ví dụ về các dạng API khác nhau. Tài liệu mang đến API thường được hỗ trợ để tạo dễ ợt cho việc áp dụng và triển khai.
Hầu hết những công ty phệ đã xây đắp API cho người tiêu dùng của chúng ta hoặc để áp dụng nội bộ.
2 tại sao cần kiểm demo API?
Các kịch phiên bản kiểm thử tự động hóa hoá mang đến GUI còn một số trong những hạn chế như:
Có thể thất bại thường xuyên nếu giao diện người dùng được update liên tục.Mất nhiều thời gian để bảo trì và tái kết cấu khi liên quan đến flaky tests.Quá trình kiểm soát tốn thời hạn và bao gồm phản hồi lờ đờ hơn so với kiểm thử API.Việc trở nên tân tiến năng đã triển khai xong về giao diện người dùng (UI) và chạy các kịch bản kiểm thử tự động hóa hoá cho tác dụng đó là một thử thách lơn trong sprint Agile 2 tuần. Không giống như các kiểm test GUI test, kiểm demo API không dựa vào giao diện bạn dùng, sẽ dễ chịu và thoải mái hơn nhiều lúc kết hợp/ tích phù hợp chúng trong khoảng đời trở nên tân tiến Agile. Ko kể ra, nó rất có thể được chuyển vào nhanh chóng hơn những ở quá trình phát triển.
Một API bao gồm các phương thức REST. Những phương thức REST này tìm, thêm mới, cập nhật hoặc xoá dữ liệu trong cơ sở dữ liệu. Các bạn cần mày mò và làm quen với các phương thức REST để tiếp cận kiểm test API. Khi đã nắm vững được các khái niệm vể API REST, chúng ta sẽ bắt đầu kiểm tra về nó. Trước hết, cần phải hiểu đồ họa của API, bao gồm:
Hành động hoàn toàn có thể thực hiện tại khi sử dụng API.Cấu trúc của requests.Cấu trúc của responses.Do đó, một bước cần thiết là để mắt tới API Documentation(tài liệu API).
3. API Documentation là gì?
API documents giống như như một tài liệu tham khảo. Nó nói tới các thông tin cần thiết của 1 API. API Documentation khôn xiết quan trọng, nó tác động trực tiếp nối việc áp dụng và sử dụng công cụ. Nếu không có bất kì ai có kiến thức về công cụ, thì sẽ không một ai biết thực hiện nó. Ngoại trừ ra, nó còn một số ưu điểm như sau:
Cung cấp 1 hướng dẫn nhanh lẹ và thuận tiện để sử dụng API.Thể hiện được các công dụng hữu ích.Tiết kiệm chi tiêu và thời gian hỗ trợ, nếu như documentation dễ dàng nắm bắt và bỏ ra tiết.API Document bao gồm các phía dẫn về kiểu cách sử dụng kết quả và tích phù hợp với một API. Nó là một trong tài liệu ngắn gọn, chứa toàn bộ các thông tin được yêu thương cầu để làm việc với API, cùng với thông tin cụ thể về các function (hàm), class (lớp), return type (kiểu dữ liệu trả về), các argument (tham số),… được hỗ trợ bởi những bài hướng dẫn và ví dụ.
3.1. Trình bày resource
Resource( tài nguyên) là tài liệu mà họ phải quản lý, hoàn toàn có thể là customers, products, posts, images, videos… khía cạnh khác, thương hiệu resource cũng trở nên xuất hiện nay trong phương pháp viết endpoint( mỗi URL kèm HTTP method của website service thì được gọi là 1 endpoint), nên nếu như khách hàng đặt tên đến resource một biện pháp khoa học, thì endpoint cũng trở thành dễ hiểu cùng dễ tiếp cận hơn.
Có thể thực hiện nhiều endpoint để truy vấn resource. Trong cùng 1 resource, một API sẽ có 1 số routes( routes nôm na là người dẫn đường mang lại Web API vẫn gọi kích hoạt nào tương đượng với uri đã làm được cung cấp) được team lại. Các tài nguyên và diễn đạt endpoint thường ngăn nắp và chủ yếu xác.
3.2. Thủ tục và endpoints
Endpoint là một phần thiết yếu ớt của API documentation. Các nhà trở nên tân tiến triển khai nó để thực hiện các request( thông tin yêu mong HTTP - là tin tức client gửi mang đến server, yêu mong server làm những gì đó). Các phương thức chỉ ra những tương tác được phép( như: GET, PUT, POST hoặc DELETE) với resource. Các bạn có thể truy cập vào links này Bookstore API để xem bộ sưu tầm API mẫu.
3.3. Parameters sử dụng
Với một url endpoint, nếu như đi với các HTTP verb khác nhau, bọn họ sẽ bao gồm endpoint không giống nhau. Vị đó, nếu và một url endpoint, cùng 1 HTTP verb, nếu con số parameters( tham số đường dẫn) khác nhau cũng trở thành tạo ra các endpoint khác nhau.
Có 4 các loại parameters:
Header parameter: là các thông số kỹ thuật kèm theo khi gửi yêu cầu lên server, chúng thường liên quan đến authorization.
Id, User
Id là 1 trong path parameter.Query parameter: bọn chúng được gắn vào thời điểm cuối URL, cùng được cung ứng sau vệt ?. Ex: /Book
Store/v1/Book?
ISBN=ISBN, ISBN là một query parameter.Request body parameters: được sử dụng trong phương thức POST, nó là một danh sách các cặp key-value( khoá-giá trị).
4. Cách áp dụng API Document
Hiện nay, có tương đối nhiều công vậy tạo API Document như: Slate, Flatdoc, Swagger,... Nhưng lại ở bài viết này, chúng ta chỉ tìm hiểu cách thực hiện API Document trên Swagger.
Để gọi hơn về kiểu cách sử dụng Swagger API documentation, chúng ta hãy truy vấn vào Bookstore API để xem cấu trúc của 1 API documentation. Khi truy cập vào Bookstore API, các các bạn sẽ thấy như hình bên dưới
Nhóm các endpoints bao gồm:
AccountBook
Store
Chúng ta cùng tò mò về request, response của một API bằng phương pháp sử dụng Swagger. Chúng ta sẽ tìm hiểu về API: Create User – POST.
Trước khi bắt đầu khám phá API, bọn họ cần tạo ra 1 người dùng có với password, tiếp đến thêm username với password trong tin tức đăng nhập của Book Store.
Bây giờ đồng hồ hãy thử chế tạo ra user
ID bằng cách sử dụng cách tiến hành POST.
Các cách thực hiện:
Expand cách thức POST đến endpoint:* /Account/v1/User* dưới Account.Click và nút Try it out.Thêm username và password, tiếp đến chọn parameter nội dung type là* application/json*. Click vào nút Execute.Swagger sẽ gửi yêu thương cầu. Chúng ta cũng có thể quan ngay cạnh được request, response trả về.
Chúng ta sẽ gửi POST Request với username cùng password ở định dạng JSON. Chúng ta nhận được mã tâm trạng 201 cùng với user
ID và sách được liên kết với username tương ứng trong phần Response body. Nó giải thích rằng yêu cầu của bọn họ đã được gửi thành công qua thứ chủ, như bạn có thể thấy trong hình trên dưới mô tả. Quanh đó ra, cách tiến hành của Swagger rất dễ dàng và hữu ích. Nó cung ứng trải nghiệm thúc đẩy để nhờ cất hộ yêu ước và dấn phản hồi cho những API.
Ngoài mô bỏng các làm việc trong API, Swagger API document còn liệt kê những mã code và response body toàn thân với tất cả các case thành công, thất bại các bạn có thể xem ở ảnh dưới:
Để kết thúc, trong bài bác đăng này, chúng ta đã gọi về API document. Chúng ta đã học tập cách áp dụng tài liệu Swagger API. Không tính ra, bọn họ đã tự làm cho quen với các loại thể nghiệm API. Tôi mong nội dung bài viết này sẽ hữu dụng với những bạn!
