YAZAPROGRAMMING LANGUAGE
Beranda / API HTTP

Testing / development · API preview

API YAZA sudah punya fondasi yang bisa dicoba.

Compiler bisa membuat starter API native, menjalankan route HTTP, memvalidasi request bertipe, dan menghasilkan kontrak OpenAPI serta koleksi Postman. Berikut kemampuan saat ini dan pekerjaan yang masih terbuka.

Prototipe, bukan rilis API produksi.

Estimasi roadmap API sekitar 50% per 28 Oktober 2026. Angka ini adalah penilaian manual terhadap release gate, bukan hasil pengukuran otomatis. Setiap gate masih memiliki pekerjaan penting yang belum selesai.

Yang sudah bisa dicoba

  • HTTP/1 nativeRequest parsing, routing, keep-alive, health, readiness, dan endpoint metrics.
  • Product CRUDContoh berlapis route → controller → service → repository dengan penyimpanan memori atau PostgreSQL.
  • Validasi bertipePath, query, header, JSON scalar, shape bertingkat, dan daftar dengan batas jumlah elemen.
  • Akses dan kebijakan routeShared Bearer, JWT HS256, CORS exact-origin, dan rate limit per client tersedia pada subset yang terdokumentasi.
  • Dokumen APICompiler dapat menghasilkan OpenAPI 3.1, Swagger-compatible JSON, dan koleksi Postman dari metadata route.
  • Request tracing IDResponse membawa X-Request-ID untuk menghubungkan response dengan event access log.

Route Product Catalog contoh

Starter layered API berisi enam operasi CRUD. {id} adalah parameter path; route list menerima parameter query limit dan offset.

src/routes/products.yz
group "/api/products":
    route GET "/" => controller ProductListController.product_controller_list
    route GET "/{id}" => controller ProductReadController.product_controller_find
    route POST "/" => controller ProductController.product_controller_create
    route PUT "/{id}" => controller ProductController.product_controller_replace
    route PATCH "/{id}" => controller ProductController.product_controller_patch
    route DELETE "/{id}" status 204 => controller ProductReadController.product_controller_delete
MethodPathFungsi
GET/api/products?limit=10&offset=0Daftar product dengan pagination.
GET/api/products/{id}Mengambil satu product berdasarkan ID.
POST/api/productsMembuat product baru.
PUT/api/products/{id}Mengganti data product.
PATCH/api/products/{id}Mengubah field yang dipilih.
DELETE/api/products/{id}Menghapus product dan mengembalikan status 204 tanpa body.
GET/healthz, /readyz, /metricsHealth check, readiness check, dan metrik operasional.

Buat dan jalankan starter

Dari root checkout YAZA di macOS Apple Silicon, CLI dapat membuat starter layered. Perintah berikut mengasumsikan binary compiler ada di dist/yaza.

Terminal
dist/yaza new --api catalog-api
cd catalog-api
../dist/yaza check src/main.yz
../dist/yaza run

Server starter mendengarkan di 127.0.0.1:3000 secara default. Gunakan YAZA_PORT untuk memilih port lain. Opsi yaza new --minimal-api membuat starter satu file tanpa struktur controller/service/repository.

Contoh request

Body product mendeklarasikan name, priceMinor, currency, dan available. Runtime memeriksa JSON terhadap tipe yang dideklarasikan sebelum mengirim nilai ke handler YAZA.

HTTP request · contoh lokal
curl -X POST http://127.0.0.1:3000/api/products \
  -H "Content-Type: application/json" \
  -d '{"name":"Headphones","priceMinor":129900,"currency":"IDR","available":true}'

Field yang hilang, salah tipe, atau tidak valid akan ditolak dengan respons error bertipe. Bentuk error dan kode status bergantung pada kondisi route; spesifikasi yang dihasilkan memuat kontrak yang diketahui compiler.

Penyimpanan, auth, dan dokumen

  • Starter menggunakan penyimpanan memori secara default. Dengan DATABASE_URL, Product CRUD dapat memakai client PostgreSQL yang ditulis dalam YAZA dan query berparameter.
  • Route bisa menetapkan auth required, auth public, atau auth jwt. JWT saat ini memakai HS256; YAZA belum menerbitkan token atau menyediakan login, OIDC/JWKS, role, maupun pencabutan terpusat.
  • Group route dapat mewariskan prefix, autentikasi, rate limit, dan kebijakan CORS exact-origin ke route di dalamnya.
  • yaza generate membuat koleksi Postman, OpenAPI 3.1, dan Swagger-compatible JSON di docs/api/. Gunakan --postman, --openapi, atau --swagger untuk memilih satu keluaran.

Yang masih dikembangkan

Jangan gunakan API preview untuk data sensitif atau layanan produksi.

API belum melewati semua release gate untuk keamanan, kompatibilitas, cakupan platform, pengujian beban, dan integrasi basis data.

  • Listener HTTP bawaan belum menyediakan TLS. Untuk deployment, dibutuhkan HTTPS reverse proxy atau load balancer yang dikonfigurasi dengan benar.
  • Handler berjalan sinkron di bounded worker pool; source YAZA belum memiliki sintaks async/await atau scheduler bahasa untuk request.
  • PostgreSQL, error mapping, dan koneksi live masih memerlukan cakupan CI lintas versi server, failure-path, sertifikat remote, dan pengujian berulang.
  • Token issuance, identitas pengguna, otorisasi berbasis kepemilikan, pencabutan pusat, dan alur lifecycle secret belum lengkap.
  • Linux end-to-end dan target Cloudflare Workers/WASI belum menjadi target rilis yang terverifikasi.

Baca panduan lengkap starter, roadmap dan release gate API, serta batas keamanan sebelum mengandalkan prototipe.