Flask / HTTP / curl

Web là cuộc hội thoại hai chiều

HTTP (Hypertext Transfer Protocol) điều hành mọi thứ. Đổi lượt nghiêm ngặt: client nói trước, server trả lời một lần, và lượt chơi kết thúc.

một request → một response → xong · mỗi cú click, mỗi lần refresh, mỗi API call đều đúng là thế này

HTTP tồn tại vì sao

Trước HTTP, mỗi cặp client–server tự phát minh phương ngữ riêng. HTTP là phương ngữ duy nhất mà tất cả cùng thống nhất.

Client vs server — hai vai trò duy nhất

Mọi ứng dụng web bạn sẽ ship đều là hai vai trò này nói chuyện. Khóa học này giúp bạn trở thành người xây đúng phía cần xây.

Điều xảy ra khi bạn click một link

Bốn nhịp, nửa giây. Mọi thứ trong khóa học này đều là phóng to một trong những nhịp này.

1. 1

   Bạn click

   Trình duyệt quyết định 'tôi cần địa chỉ đó' và dựng một request: URL, method (GET), headers — một tin nhắn text nhỏ.

2. 2

   Nó đi qua mạng

   Request đi qua mạng đến đúng máy, đúng cổng. (TLS mã hóa chuyến đi — chủ đề sau này.)

3. 3

   Server làm việc

   Server chuyển request sang ứng dụng của bạn. Ứng dụng làm việc: đọc dữ liệu, chạy logic, dựng trang hay JSON.

4. 4

   Bạn thấy pixel

   Response đi về. Trình duyệt phân tích HTML, áp dụng CSS, chạy JS, và vẽ. Xong — cho đến cú click tiếp theo.

Một request gồm bốn phần

Tất cả những gì client có thể nói, gói trong một tin nhắn. Không hơn, không kém.

Một trao đổi thật, không cần trình duyệt

Đây chính là thứ di chuyển giữa client và server. Trái: request (method + URL + headers + body). Phải: response (status + headers + body).

GET /users/42?sort=new HTTP/1.1
Host: api.shop.com
Content-Type: application/json

{"name": "Ada"}

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 46

{"id": 42, "name": "Ada", "posts": 3}

Giải phẫu một địa chỉ

Mỗi URL là năm công việc trong một dòng. Trình duyệt và server tách nó ra theo cùng một cách mỗi lần.

https://api.shop.com:8443/users/42?sort=new&page=2

scheme   https          how to talk
host     api.shop.com   which machine answers
port     :8443          which door (80 and 443 are the defaults)
path     /users/42      which resource
query    ?sort=new...   options, as key=value pairs

Đa số thời gian cổng bị giấu — :80 cho http, :443 cho https được ngầm hiểu.

Một response gồm ba phần

Ảnh phản chiếu của request — nhưng nó bắt đầu bằng một phán quyết: mã trạng thái.

Methods — các động từ của web

Method là lời cam kết về ý định. Bạn và server đều có thể dựa vào nó: GET không bao giờ thay đổi gì, POST tạo mới, DELETE xóa.

Chọn đúng động từ

Chọn theo ý định, không theo thói quen. Method nói cho cache, trình duyệt và app khác biết endpoint của bạn an toàn để đụng đến ra sao.

Status code — câu trả lời một dòng của server

Mọi response bắt đầu bằng một số ba chữ số. Chữ số đầu kể trọn câu chuyện trong một cái nhìn.

Chín mã bạn sẽ thực sự gặp

Ghi nhớ khuôn mẫu, không phải danh sách: 2xx xong, 3xx đi nơi khác, 4xx lỗi của bạn, 5xx lỗi của chúng tôi.

401 vs 403 — danh tính, rồi quyền

Cặp hay nhầm nhất trong HTTP. 401 là vấn đề danh tính; 403 là vấn đề quyền.

Bốn headers trả lời những câu hỏi thường gặp

Có tổng cộng ~100 headers. Bốn cái này trả lời những câu hỏi xuất hiện nhiều nhất.

Vũ khúc redirect

Redirect không phải lỗi — nó là tấm biển chỉ đường. Bạn không viết nó, bạn chỉ xem nó diễn ra.

1. 1

   Bạn gọi địa chỉ cũ

   GET /old-page. Server biết nó đã dời — nhưng không gửi trang, nó gửi một tấm biển chỉ đường.

2. 2

   Server chỉ đường

   301 + header Location: /new-page. Một response nhỏ xíu, không nội dung — chỉ là 'sang đó mà'.

3. 3

   Trình duyệt tự tuân theo

   Nó gọi lại URL mới, nhận 200, và hiển thị trang. Từ chỗ ngồi của bạn, nó chỉ như một cú click.

Web server thực sự làm gì

Bỏ qua phần quảng cáo: một web server là chương trình lặp lại bốn bước, hàng nghìn lần mỗi giây.

1. 1

   Lắng nghe trên một cổng

   Nó chờ trên một cổng (80 cho HTTP, 443 cho HTTPS) các kết nối đến — như để điện thoại luôn sẵn sàng nghe gọi.

2. 2

   Phân tích request

   Nó giải mã các byte thành method, URL, headers, body — bốn phần đã nói ở trên.

3. 3

   Chạy code của bạn

   Nó chuyển request sang ứng dụng của bạn (Flask trong khóa này), nơi quyết định làm gì — thường là: đọc dữ liệu, dựng trang.

4. 4

   Gửi response

   Nó gói kết quả thành status + headers + body và gửi lại. Rồi quay về bước 1.

Cổng là một số cửa

Một máy chạy nhiều dịch vụ; cổng chọn cánh cửa. Production trả lời ở 80/443; dev server của Flask thường mở 5000.

Flask trong bốn câu

Framework là bộ khung bạn không phải tự xây. Flask là bộ khung nhẹ nhất trong các framework Python web phổ biến.

Cả một website, 8 dòng

Đây là một ứng dụng web hoàn chỉnh, chạy được. Hai route: một cho người (HTML), một cho máy (JSON).

from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/")
def home():
    return "<h1>Hello, shipper!</h1>"

@app.route("/api/hello")
def api_hello():
    return jsonify(name="shipper", status="alive")

Chạy flask run, mở http://127.0.0.1:5000 — đó là toàn bộ phía server của một ứng dụng web.

Hai terminal, zero trình duyệt

Đó là toàn bộ vòng lặp: Python trên máy bạn trả lời HTTP trên một cổng. Bạn test được trước khi người nào thấy nó.

Route cận cảnh

Khi đã biết lời hứa, route chỉ là biểu mẫu đăng ký. Bốn chi tiết đáng biết.

Ba cách trả lời

Cùng app, ba kiểu trả về. Giá trị trả về quyết định client nhận gì — và ở mã trạng thái nào.

from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/")
def page():
    return "<h1>Hello, shipper!</h1>"   # -> text/html

@app.route("/api/hello")
def api():
    return jsonify(name="shipper")      # -> application/json

@app.route("/missing")
def gone():
    return "not here", 404               # -> you pick the status

Một quy tắc cần nhớ: hàm trả về gì, Flask tự gói thành status + headers + body.

HTML cho mắt, JSON cho máy

Một app thường làm cả hai: route HTML cho người, route /api cho máy.

Bốn cánh cửa client có thể gõ

Client gửi dữ liệu theo nhiều hình dạng; Flask mở mỗi hình dạng ở một chỗ riêng. Biết nhìn đúng chỗ, cú pháp tự theo sau.

from flask import request

@app.route("/users/<int:uid>")       # 1. URL parameter
def show_user(uid):
    return jsonify(uid=uid)

@app.route("/search")
def search():
    q    = request.args.get("q")    # 2. query string: /search?q=shoes
    name = request.form.get("name") # 3. form field (login, checkout...)
    body = request.json              # 4. JSON body (from an API client)

Một ứng dụng, bốn lối vào. <uid> đến từ URL; phần còn lại nằm trên đối tượng request.

Mỗi loại dữ liệu đáp xuống đâu

Ghép kênh với việc — đó là toàn bộ quyết định thiết kế phía sau mọi API.

Đọc query string, an toàn

Giá trị query đến dưới dạng chuỗi — kể cả '42'. Đặt giá trị mặc định, và tự chuyển kiểu.

@app.route("/search")
def search():
    q = request.args.get("q", "")              # ?q=shoes -> "shoes", else ""
    page = request.args.get("page", 1, type=int)  # ?page=2 -> 2 (an int)
    if not q:
        return "nothing to search", 400
    return jsonify(q=q, page=page)

get(key, default, type=...) là giải pháp 90% cho query string.

Bên trong một request của Flask

Bốn trạm giữa 'byte đến' và 'byte đi'. Hiểu route giúp gỡ lỗi nhanh gấp 10 lần.

1. 1

   Server nhận

   Web server (hay dev server của Flask) nhận byte HTTP thô và chuyển cho Flask.

2. 2

   Flask khớp route

   Nó đi qua các lời hứa đã đăng ký: method + URL. Không khớp? 404 ngay lập tức — code của bạn không chạy.

3. 3

   Hàm của bạn chạy

   Hàm view đọc input (args, form, json), làm việc — thường là: lấy dữ liệu — rồi trả về một giá trị.

4. 4

   Flask gói và gửi

   Giá trị trả về thành status + headers + body, và đi về phía client. Vòng đi-về khép lại.

Lỗi chỉ là mã trạng thái

Dev server của Flask hiển thị traceback đầy đủ khi 500 — dòng cuối thường chỉ đúng lỗi. Sửa, lưu, curl lại.

Trả về lỗi có chủ đích

Một app đúng chuẩn sẽ lỗi lịch sự: mã đúng nói cho client biết chính xác nên thử gì tiếp.

Vì sao lập trình viên sống trong curl

curl là người anh em thô mộc và trung thực của trình duyệt: nó cho thấy phần ống dẫn mà trình duyệt giấu.

Một app, bốn câu trả lời

Thành công, dữ liệu, dữ liệu lọc, thất bại. Đây là cảm giác test một API.

Sáu cờ, đủ 95% việc test API

Mặc định của curl là: GET một URL và in body. Các cờ biến nó thành client API đầy đủ.

Tạo một bản ghi từ terminal

Method + header + body + URL. Một khuôn mẫu này đáp ứng phần lớn việc 'gửi dữ liệu vào API của bạn'.

# the classic "create a record" one-liner
curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"name": "Ada"}' \
  http://127.0.0.1:5000/users

# ...and check what the server actually said
curl -i -X POST \
  -H 'Content-Type: application/json' \
  -d '{"name": "Ada"}' \
  http://127.0.0.1:5000/users

Với -i bạn nên thấy HTTP/1.1 201 CREATED — bằng chứng bản ghi đã ra đời.

-v: xem cuộc hội thoại diễn ra

Dòng bắt đầu bằng > là của bạn; dòng bắt đầu bằng < là của server. Đây là toàn bộ giao thức, ngay trước mắt bạn.

Toàn bộ stack trong một bức tranh

Ba vai trò, một đường ống — và chủ đề tiếp theo (nginx) cắm vào đúng chỗ này.

client nói chuyện với cánh cửa · cánh cửa nói chuyện với ứng dụng · ứng dụng nói chuyện với thế giới — tất cả bằng HTTP thuần