Thiết kế API cho thiết bị là một khóa Advanced trong chuỗi Coding. Mỗi bài học mở mạch đèn WiFi (một LED ở chân GPIO 8) bằng một sketch C++ mới, và bạn trò chuyện với chiếc đèn như một ứng dụng sẽ làm: request, mã trạng thái và JSON. Khóa học mất khoảng sáu tiếng.
Những gì bạn xây dựng, bài học này qua bài học khác
- Resources and routes: a routing table, paths that name things, and why
GET /turnOnis a bug that switches the lamp on at 3 in the morning. You add a/deviceresource of your own. - Phương thức: PUT thay thế, PATCH sửa một phần, POST tạo mới (201 và một Location), DELETE xóa (204). An toàn và idempotent, và một 405 kèm header Allow cho phương thức mà đường dẫn không nhận.
- Schema JSON: hợp đồng của chiếc đèn dưới dạng JSON Schema, một PUT kiểm tra mọi trường và trả lời 422 với mọi lỗi cùng lúc, và từ chối một trường viết sai chính tả thay vì bỏ qua nó.
- Lỗi: 400, 409, 422 và 503, một Retry-After báo khi nên thử lại, một dạng lỗi duy nhất cho mọi lỗi, và các luật thử lại mà client nên tuân theo.
- Token xác thực: bearer token, 401 với 403, phép so sánh trong thời gian hằng số, token không ghi vào log, và một câu trả lời trung thực về nơi một thiết bị thật giữ bí mật của nó (không trong sketch, và chỉ qua TLS).
- Phiên bản: một lần đổi tên phá tính tương thích nhận
/v2,/v1vẫn chạy kèm ngày Sunset, cả hai là hai góc nhìn của cùng một chiếc đèn, và một trường mới thêm vào thì chẳng cần phiên bản mới nào cả.
Trùm cuối: một API đèn có tài liệu
Bài học cuối cùng hoàn thiện phiên bản 1 của toàn bộ API: các route, các method, một schema đã kiểm tra, một dạng lỗi thống nhất và token. Bảng định tuyến là nguồn sự thật duy nhất, nên GET /v1/docs được sinh ra từ đó và không thể lệch khỏi code. Một bộ kiểm thử hợp đồng (kiểu test) gọi mười bốn trường hợp đúng như một client sẽ làm, phần lớn là lỗi, và in ra contract: 14 of 14 passed. Bạn thêm một route kiểm tra sức khỏe kèm tài liệu và kiểm thử của nó chỉ trong ba dòng, rồi viết hướng dẫn API mà lập trình viên ứng dụng sẽ cần.
Cách các request đến được bóng đèn
The editor's network is simulated (see WiFi, mô phỏng):
client duy nhất có thể truy cập web server trên bo mạch là panel Web, và nó chỉ gửi GET không kèm header. Một khóa học về API cần PUT, PATCH, DELETE, body JSON và header Authorization, nên mỗi sketch có một lối vào thứ hai: serial monitor đóng vai một curl nhỏ. Gõ PUT /lamp {"on":true,"brightness":40} and it
prints the status, one header and the body. Both ways in reach the same
route() function, which is good design anyway: a handler should not care
how a request arrived.
Mạng mô phỏng không có TLS, nên mọi byte đều đọc được. Các token trong sketch là token demo, cố tình công khai, và bài học về xác thực sẽ nói một sản phẩm thật phải làm gì thay thế.
Trước khi bắt đầu
Bạn cần thành thạo C++ trên ESP32-C3 cũng như WiFi và web server trên đó. Connected devices bao quát phần mạng. Sau khóa học này, Distributed systems with three boards sẽ tiếp nhận các ý tưởng về retry và idempotence rồi áp dụng trên ba bo mạch.