Pelajaran dan game belajarnya

Rancang API perangkat

Rancang HTTP API untuk lampu di ESP32-C3, satu pelajaran demi satu pelajaran, dari route pertama sampai dokumentasi yang dibuat otomatis dan contract test.

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 /turnOn is a bug that switches the lamp on at 3 in the morning. You add a /device resource 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, /v1 tetap 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.