Rancang API perangkat adalah kursus Lanjutan di jalur Coding. Setiap pelajaran membuka rangkaian lampu WiFi (sebuah LED di GPIO 8) dengan sketch C++ baru, dan kamu berbicara dengan lampu itu seperti layaknya sebuah aplikasi: request, kode status dan JSON. Butuh sekitar enam jam.
Apa yang kamu bangun, pelajaran demi pelajaran
- 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. - Method: PUT mengganti, PATCH mengubah sebagian, POST membuat (201 dan sebuah Location), DELETE menghapus (204). Safe dan idempotent, serta 405 dengan header Allow untuk method yang tidak diterima sebuah path.
- Skema JSON: kontrak lampu sebagai JSON Schema, sebuah PUT yang memeriksa setiap field dan menjawab 422 dengan semua masalah sekaligus, dan menolak field yang salah tulis alih-alih mengabaikannya.
- Error: 400, 409, 422 dan 503, sebuah Retry-After yang menyebut kapan harus mencoba lagi, satu bentuk error untuk semua error, dan aturan retry yang sebaiknya diikuti klien.
- Token auth: bearer token, 401 lawan 403, pembandingan constant-time, token yang dijauhkan dari log, dan kisah jujur tentang di mana perangkat sungguhan menyimpan rahasianya (bukan di sketch, dan hanya lewat TLS).
- Versioning: penggantian nama yang breaking mendapat
/v2,/v1tetap bekerja dengan tanggal Sunset, keduanya adalah tampilan dari satu lampu yang sama, dan field tambahan tidak butuh versi baru sama sekali.
Boss: API lampu berdokumentasi
Pelajaran terakhir menghasilkan versi 1 dari seluruh API: routes, methods, schema yang tervalidasi, satu bentuk error, dan token. Tabel routing adalah satu-satunya sumber kebenaran, jadi GET /v1/docs dihasilkan darinya dan tidak bisa berbeda dari kode. Satu rangkaian tes kontrak (tipe test) memanggil empat belas kasus seperti yang dilakukan klien, sebagian besar berupa error, dan mencetak contract: 14 of 14 passed. Kamu menambahkan route health beserta docs dan tesnya dalam tiga baris, lalu menulis panduan API yang dibutuhkan pengembang aplikasi.
Bagaimana request sampai ke lampu
The editor's network is simulated (see WiFi, disimulasikan):
satu-satunya klien yang bisa mengakses web server di board adalah panel Web, dan panel itu mengirim GET tanpa header. Kursus API butuh PUT, PATCH, DELETE, body JSON, dan header Authorization, jadi setiap sketch punya jalan masuk kedua: serial monitor adalah semacam curl mini. Ketik 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.
Tidak ada TLS di jaringan simulasi, jadi setiap byte bisa dibaca. Token di sketch adalah token demo, memang dibuat publik, dan pelajaran auth menjelaskan apa yang harus dilakukan sebuah produk sungguhan.
Sebelum kamu mulai
Kamu sebaiknya sudah nyaman dengan C++ di ESP32-C3 serta dengan WiFi dan web server di atasnya. Connected devices membahas sisi jaringannya. Setelah itu, Distributed systems with three boards mengambil ide retry dan idempotence dan menjalankannya di tiga board.