3xx: Redirection Chuyển hướng: Mã trạng thái này cho biết client cần có thêm action để hoàn thành request 4xx: Client Error Lỗi Client: Nó nghĩa là request chứa cú pháp không chính xá
Trang 1
TRƯỜNG ĐẠI HỌC THĂNG LONG
KHOA TOÁN TIN
LẬP TRÌNH PYTHON
HƯỚNG DẪN VỀ CÁCH SỬ DỤNG API CHO MỘT SỐ TRƯỜNG HỢP SỬ DỤNG PHỔ BIẾN TẠI MANGADEX
HIỆN
Hồ Hồng Trường A40643 – Nguyễn Đình Đạt
A40639 – Nguyễn Thanh Ngân
A40810 – Phạm Dương Duy
A40985 – Bùi Tiến Dũng
Trang 2HÀ NỘI – 2023
LỜI CẢM ƠN
Lời đầu tiên em xin chân thành cảm ơn thầy Hồ Hồng Trường – giảng viên môn Lập trình Python, đã hỗ trợ, hướng dẫn và giải đáp những thắc mắc của em trong suốt quá trình thực hiện để em có thể hoàn thành tốt bài tập lớn cuối kỳ của mình
Quá trình thực hiện, nhóm đã vận dụng những kiến thức được giảng dạy đồng thời tìm hiểu thêm từ những nguồn thông tin bên ngoài để có thể phát triển hơn ý tưởng của nhóm Dù vậy, vẫn không thể tránh khỏi những sai sót xảy ra trong quá trình tìm hiểu và thực hiện
Do đó, em luôn mong nhận được sự góp ý từ thầy để hiểu
rõ hơn về kiến thức liên quan đến môn học, cũng như có được kinh nghiệm để tiếp tục thực hiện các đề tài, dự án tiếp theo trong thời gian tới Em xin chân thành cảm ơn Thầy rất nhiều!
Trang 3MỤC LỤC
LỜI CẢM ƠN 2
PHẦN 1 : PHÂN CHIA CÔNG VIỆC 3
PHẦN 2 : GIỚI THIỆU VỀ API 3
PHẦN 3 : GIỚI THIỆU VỀ ĐỀ TÀI CỦA NHÓM 4
PHẦN 4 : MÔ TẢ CÁC ENDPOINT 4
PHẦN 5 : MÔ TẢ SWAGGER IU 5
Trang 4PHẦN 1 : PHÂN CHIA CÔNG VIỆC
1 A40643 Nguyễn Đình Đạt (nhóm trưởng) : code, chuẩn bị tài liệu đề tài
2 A40639 Nguyễn Thanh Ngân : Chuẩn bị tài liệu swagger UI, làm báo cáo
3 A40810 Phạm Dương Duy : làm slide
4 A40985 Bùi Tiến Dũng : thuyết trình
PHẦN 2 : GIỚI THIỆU VỀ API
API là viết tắt của Application Programming Interface – phương thức trung gian kết nối các ứng dụng và 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 hay dùng, từ đó có thể trao đổi dữ liệu giữa các ứng dụng API được xây dựng dựa trên chính 2 thành phần : Request
và Reponse
Về Request : 1 request đúng chuẩn cần 4 thứ :
1 URL
URL là địa chỉ duy nhất cho 1 request, thường là đường dẫn tới một hàm xử lý logic
2 Method
HTTP request có tất cả 9 loại method , 2 loại được sử dụng phổ biến nhất là GET và POST
GET: Sử dụng để lấy thông tin từ server theo URI đã cung cấp
HEAD: Giống với GET nhưng response trả về không
có body, chỉ có header
POST: Gửi thông tin tới sever thông qua các parameters HTTP
PUT: Ghi đè tất cả thông tin của đối tượng với những
gì được gửi lên
Trang 5 PATCH: Ghi đè các thông tin được thay đổi của đối tượng
DELETE: Xóa resource trên server
CONNECT: Thiết lập một kết nối tới server theo URI
OPTIONS: Mô tả các tùy chọn giao tiếp cho
resource
TRACE: Thực hiện một bài test loop-back theo đường dẫn đến resource
3 Header
Là nơi chứa các thông tin cần thiết của 1 request nhưng end-users không biết có sự tồn tại của nó Ví dụ: độ dài của request body, thời gian gửi request, loại thiết bị đang
sử dụng, loại định dạng cái response mà client có đọc được…
4 Body
Là nơi chứa thông tin mà client sẽ điền
Về Response :
Sau khi nhận được request từ phía client, server sẽ xử lý cái request đó và gửi ngược lại cho client 1 cái response Cấu trúc của 1 response tương đối giống phần request nhưng Status code sẽ thay thế cho URL và Method Tóm lại, nó có cầu trúc 3 phần:
Status code
Headers
Body
Phần Header và body tương đối giống với request
Status code của response
Status code (Mã hóa trạng thái thường được gọi là mã trạng thái) là một số nguyên 3 ký tự, trong đó ký tự đầu tiên của Status-Code định nghĩa loại Response và hai ký
tự cuối không có bất cứ vai trò phân loại nào Có 5 giá trị của ký tự đầu tiên:
1xx: Information (Thông tin): Khi nhận được những
mã như vậy tức là request đã được server tiếp nhận
và quá trình xử lý request đang được tiếp tục
2xx: Success (Thành công): Khi nhận được những
mã như vậy tức là request đã được server tiếp nhận, hiểu và xử lý thành công
Trang 6 3xx: Redirection (Chuyển hướng): Mã trạng thái này cho biết client cần có thêm action để hoàn thành request
4xx: Client Error (Lỗi Client): Nó nghĩa là request chứa cú pháp không chính xác hoặc không được thực hiện
5xx: Server Error (Lỗi Server): Nó nghĩa là Server thất bại với việc thực hiện một request nhìn như có
vẻ khả thi
PHẦN 3 : GIỚI THIỆU VỀ ĐỀ TÀI CỦA NHÓM
Mục đích của tài liệu này là cung cấp hướng dẫn về cách sử dụng API cho một số trường hợp sử dụng phổ biến tại mangadex
Sửa chữa các thông tin của manga
Lấy thông của các manga xong tổng hợp thành báo cáo
PHẦN 4 : MÔ TẢ CÁC ENDPOINT
1 GET "/": Endpoint này trả ra thông báo chào mừng
và hướng dẫn người dùng truy cập trang tài liệu API
2 GET "/manga": Endpoint trả ra tất cả các thông tin của các manga có trong cơ sở dữ liệu
3 GET "/manga/rating": Endpoint này trả ra các manga có điểm rating lớn hơn rating mà người dùng yêu cầu
4 GET "/manga/view/id": Endpoint này trả ra tổng số lượt xem của một manga cụ thể dựa theo ID mà người dùng yêu cầu
5 GET "/manga/genre": Endpoint này trả ra các manga có thể loại mà người dùng yêu cầu
6 GET "/manga/author": Endpoint này trả ra các manga có tác giả mà người dùng yêu cầu
7 GET "/manga/status": Endpoint này trả ra các manga có trạng thái mà người dùng yêu cầu
8 GET "/manga/chapter/id": Endpoint này trả ra số chapter của 1 manga dựa theo ID mà người dùng yêu cầu
9 GET "/manga/other_name": Endpoint này trả ra tên khác của một manga dựa theo ID mà người dùng yêu cầu
Trang 710 POST "/addManga": Endpoint này cho phép người dùng thêm 1 manga mới vào cơ sở dữ liệu với các thông tin tên truyện tranh, tác giả, trạng thái, thể loại và xếp hạng được người dùng cung cấp Kết quả trả về là ID của truyện tranh mới được thêm vào
11 POST "/manga/rating": Endpoint này cập nhật xếp hạng của manga trong cơ sở dữ liệu với ID và rating manga được cung cấp Điểm cuối trả về thông báo xác nhận cập nhật thành công
12 POST "/manga/addchapter": Endpoint này thêm một chương mới vào truyện tranh trong cơ sở
dữ liệu với ID chương, ID truyện tranh, tên chương
và số lượt xem được cung cấp Điểm cuối trả về thông báo xác nhận cập nhật thành công
13 POST "/manga/status": Endpoint này cập nhật trạng thái của truyện tranh trong cơ sở dữ liệu với
ID và trạng thái truyện tranh được cung cấp Điểm cuối trả về thông báo xác nhận cập nhật thành công
14 POST "/manga/genre": Endpoint này cập nhật thể loại truyện tranh trong cơ sở dữ liệu với thể loại
và ID truyện tranh được cung cấp Điểm cuối trả về thông báo xác nhận cập nhật thành công
15 POST "/manga/other_name": Endpoint này cập nhật tên khác của truyện tranh trong cơ sở dữ liệu với ID truyện tranh được cung cấp và tên khác của truyện tranh Điểm cuối trả về thông báo xác nhận cập nhật thành công
16 POST "/manga/author": Endpoint này cập nhật tác giả của manga trong cơ sở dữ liệu với ID manga
và tên tác giả được cung cấp Điểm cuối trả về thông báo xác nhận cập nhật thành công
17 POST "/manga/name": Endpoint này cập nhật tên truyện tranh trong cơ sở dữ liệu với ID truyện tranh và tên truyện tranh được cung cấp Điểm cuối trả về thông báo xác nhận cập nhật thành công
PHẦN 5 : MÔ TẢ SWAGGER IU
1 GET "api_url/":
Trang 8Params : No
Response
"Chào bạn, hãy truy cập
http://127.0.0.1:8000/docs để xem hướng dẫn sử dụng Api"
Test - Bạn có thể gọi ngay trên trình duyệt http://127.0.0.1:8000/
2 GET "api_url/manga":
Params : No
Response
[
{
"id": , 1
"manga_name": "One Piece" ,
"other_name": "ワンピース" ,
"author": "Eiichiro Oda" ,
"status": "Ongoing" ,
"genre": "Action" ,
"rating": 10
},
{
"id": , 2
"manga_name": "Naruto" ,
"other_name": "ナルト" ,
"author": "Masashi Kishimoto" ,
"status": "Completed" ,
"genre": "Action, Adventure, Comedy" ,
"rating": 8
}]
Test - Bạn có thể gọi ngay trên trình duyệt http://127.0.0.1:8000/manga
3 GET "api_url/manga/rating"
Trang 9Params :
rating Bắt buộc Điểm xếp hạng mà bạn yêu cầu
Response
[
{
"id": , 1
"manga_name": "One Piece" ,
"other_name": "ワンピース" ,
"author": "Eiichiro Oda" ,
"status": "Ongoing" ,
"genre": "Action" ,
"rating": 3.12
},]
Test - Bạn có thể gọi ngay trên trình duyệt http://127.0.0.1:8000/manga/rating?rating=3
4 POST "api_url/manga/rating"
Params :
cầu
mà bạn yêu cầu
Respones
{
"message": "Đã cập nhật đánh giá mới cho Manga: 1 thành: 3.0"
}
Test – bạn có thể gọi ngay trên trình duyệt http://127.0.0.1:8000/manga/rating?
manga_id=1&rating=3
5 GET "api_url/manga/view/id"
Params
Trang 10Id Bắt buộc Id mà bạn yêu
cầu
Respones
0
Test – bạn có thể gọi ngay trên trình duyệt http://127.0.0.1:8000/manga/view/id?id=5
6 GET "api_url/manga/genre"
Params
muốn
Respones
[
{
"id": , 2
"manga_name": "Naruto" ,
"other_name": "ナルト" ,
"author": "Masashi Kishimoto" ,
"status": "Completed" ,
"genre": "Action, Adventure, Comedy" ,
"rating": 8
},
{
"id": , 3
"manga_name": "Attack on Titan" ,
"other_name": "進撃の巨人" ,
"author": "Hajime Isayama" ,
"status": "Ongoing" ,
"genre": "Action, Drama, Horror" ,
"rating": 8
},
{
"id": , 4
"manga_name": "Demon Slayer: Kimetsu no Yaiba" ,
"other_name": "鬼滅の刃" ,
"author": "Koyoharu Gotouge" ,
Trang 11"status": "Completed" ,
"genre": "Action, Historical, Supernatural" , "rating": 8
}
]
Test – bạn có thể gọi ngay trên trình duyệt http://127.0.0.1:8000/manga/genre?
genre=Action
7 POST "api_url/manga/genre"
Params
muốn
Responses
{
"message": "Đã cập nhật thể loại mới cho Manga: 4 thành: Action"
}
Test – bạn có thể gọi trực tiếp trên trình duyệt http://127.0.0.1:8000/manga/genre?
manga_id=4&genre=Action
8 GET "api_url/manga/author"
Params
Responses
[
{
"id": , 2
"manga_name": "Naruto" ,
"other_name": "ナルト" ,
"author": "Masashi Kishimoto" ,
"status": "Completed" ,
Trang 12"genre": "Action, Adventure, Comedy" ,
"rating": 8
}
]
Test – bạn có thể gọi trực tiếp trên trình duyệt http://127.0.0.1:8000/manga/author?
author=Masashi%20Kishimoto
9 POST "api_url/manga/author"
Params
muốn
Responses
{
"message": "Đã cập nhật tác giả mới cho
Manga: 4 thành: Koyoharu Gotouge"
}
Test – bạn có thể gọi trực tiếp trên trình duyệt http://127.0.0.1:8000/manga/author?
manga_id=4&n_author=Koyoharu%20Gotouge
10 GET "api_url/manga/status"
Params
mà bạn muốn
Responses
Chưa hoàn thành (Incomplete)
[
{
"id": , 6
"manga_name": "Test01" ,
"other_name": "Muahaha" ,
"author": "Test01" ,
"status": "Incomplete" ,
Trang 13"genre": "Test01" ,
"rating": 7
}
]
Đã hoàn thành (Complete)
[
{
"id": , 3
"manga_name": "Attack on Titan" ,
"other_name": "進撃の巨人" ,
"author": "Hajime Isayama" ,
"status": "Complete" ,
"genre": "Action, Drama, Horror" ,
"rating": 8
}
]
Test – bạn có thể gọi trực tiếp trên trình duyệt http://127.0.0.1:8000/manga/status?
status=Incomplete
http://127.0.0.1:8000/manga/status?
status=Complete
11 POST "api_url/manga/status"
Params
bạn muốn
Responses
{
"message": "Đã cập nhật trạng thái mới cho Manga: 6 thành: Complete"
}
Test – bạn có thể gọi trực tiếp trên trình duyệt http://127.0.0.1:8000/manga/status?
manga_id=6&status=Complete
Trang 1412 GET "api_url/manga/other_name"
Params
Responses
"Tên khác của manga Attack on Titan là: 進撃の巨 人"
Test – bạn có thể gọi trực tiếp trên trình duyệt http://127.0.0.1:8000/manga/other_name?id=3
13 POST "api_url/manga/other_name"
Params
muốn
Responses
{
"message": "Đã cập nhật tên khác mới cho Manga: 2 thành: Naruto"
}
Test – bạn có thể gọi trực tiếp trên trình duyệt http://127.0.0.1:8000/manga/other_name? manga_id=2&other_name=Naruto
14 POST "api_url/addManga "
Params
truyện
mà bạn yêu cầu
Trang 15{
"Manga bạn thêm có id": 13
}
Test – bạn có thể gọi trực tiếp trên trình duyệt http://127.0.0.1:8000/addManga?
manga_name=Naruto&author=Masashi
%20Kishimoto&status=Completed&rating=8
15 POST "api_url/manga/name"
Params
muốn
Responses
{
"message": "Đã cập nhật tên mới cho Manga: 7 thành: Naruto"
}
Test – bạn có thể gọi trực tiếp trên trình duyệt http://127.0.0.1:8000/manga/name?
manga_id=7&name=Naruto
16 GET"api_url/manga/chapter/id"
Params
Responses
0
Test – bạn có thể gọi trực tiếp trên trình duyệt http://127.0.0.1:8000/manga/chapter/id? id=10
Trang 1617 POST"api_url/manga/addchapter "
Params
Responses
{
"detail": "id_chapter này đã tồn tại , vui lòng sử dụng id_chpater khác"
}
Test – bạn có thể gọi trực tiếp trên trình duyệt http://127.0.0.1:8000/manga/addchapter? id_chapter=4&id_manga=6&chap_name=Hokage
%20vs.%20Hokage%21%21&view=0