REST API: apa itu, metode HTTP dan prinsip kerja dalam aplikasi mobile

Apa itu REST API?

REST API (Representational State Transfer API) — adalah gaya arsitektur yang diusulkan oleh Roy Fielding dalam disertasi doktornya pada tahun 2000. Ini mendefinisikan serangkaian batasan dan prinsip untuk merancang protokol jaringan. API yang mematuhi batasan ini disebut RESTful. REST bukanlah protokol atau standar — ini adalah pendekatan arsitektur yang menggunakan protokol yang ada (terutama HTTP) untuk pertukaran data antara klien dan server.

Ide kunci REST adalah arsitektur berorientasi sumber daya. Alih-alih memanggil metode di server (seperti dalam SOAP atau RPC), klien beroperasi pada sumber daya: mendapatkan daftarnya, membuat yang baru, memperbarui, atau menghapus. Setiap sumber daya adalah entitas domain: pengguna, pesanan, produk, artikel. Sumber daya memiliki status yang dikirimkan ke klien dalam format standar, biasanya JSON. Server tidak menyimpan status klien di antara permintaan — ini adalah prinsip stateless, persyaratan kunci REST.

Karakteristik utama REST API:

• Stateless — setiap permintaan dari klien berisi semua informasi yang diperlukan untuk pemrosesannya
• Cacheable — respons server harus secara eksplisit ditandai sebagai dapat di-cache atau tidak
• Layered system — arsitektur dapat mencakup server perantara, penyeimbang beban, proxy
• Uniform interface — antarmuka interaksi seragam melalui metode HTTP, URL, dan kode status

Prinsip arsitektur REST

REST didasarkan pada enam batasan arsitektur yang dirumuskan oleh Fielding. Kepatuhan terhadap batasan ini menjamin skalabilitas, kinerja, dan kemudahan integrasi. Setiap prinsip memecahkan masalah spesifik sistem terdistribusi — dari kebutuhan caching hingga persyaratan keamanan. Mari kita bahas setiap prinsip secara detail.

Prinsip Uniform Interface juga mencakup empat sub-batasan: identifikasi sumber daya melalui URI, manipulasi sumber daya melalui representasi, pesan yang mendeskripsikan diri sendiri, dan HATEOAS (hypermedia sebagai mesin status aplikasi). Sub-batasan terakhir ini sering diabaikan dalam praktik — sebagian besar REST API modern tidak mengimplementasikan HATEOAS sepenuhnya, yang menyebabkan perdebatan tentang apakah API semacam itu ‘benar-benar’ RESTful.

Prinsip Stateless — salah satu yang terpenting untuk penskalaan. Tidak adanya sesi di server berarti setiap instance server dapat memproses permintaan apa pun. Ini menyederhanakan penskalaan horizontal: cukup tambahkan server baru di belakang penyeimbang beban. Untuk aplikasi mobile, stateless juga berarti bahwa permintaan dapat dikirim ke server CDN mana pun, yang sangat penting untuk ketersediaan global.

Metode HTTP dalam REST

Setiap metode HTTP dalam REST API sesuai dengan operasi tertentu pada sumber daya: GET untuk membaca, POST untuk membuat, PUT untuk pembaruan penuh, PATCH untuk pembaruan sebagian, DELETE untuk menghapus. Idempotensi metode adalah karakteristik kunci: GET, PUT, DELETE bersifat idempoten (eksekusi berulang memberikan hasil yang sama), POST dan PATCH tidak. Ini penting untuk menangani kesalahan jaringan saat klien tidak tahu apakah permintaan telah mencapai server.

• GET — mendapatkan sumber daya atau daftar sumber daya. Idempoten, tidak mengubah status server
• POST — membuat sumber daya baru. Tidak idempoten, setiap panggilan membuat sumber daya baru
• PUT — penggantian penuh sumber daya. Idempoten, panggilan berulang tidak mengubah status setelah yang pertama
• PATCH — pembaruan sebagian sumber daya. Sebagian idempoten (tergantung implementasi)
• DELETE — penghapusan sumber daya. Idempoten, penghapusan berulang mengembalikan 404, bukan kesalahan

Kode status HTTP adalah bagian integral dari REST API. Setiap kode memiliki arti tertentu: 200 OK untuk GET berhasil, 201 Created untuk POST, 204 No Content untuk DELETE tanpa tubuh respons, 400 Bad Request untuk data tidak valid, 401 Unauthorized saat tidak ada autentikasi, 404 Not Found saat sumber daya tidak ada. Penggunaan kode status yang benar membuat API dapat mendokumentasikan dirinya sendiri dan menyederhanakan debugging.

Format data: JSON dan lainnya

JSON (JavaScript Object Notation) — format utama transmisi data dalam REST API. Popularitasnya dijelaskan oleh kesederhanaan, keterbacaan manusia, dan dukungan asli dalam JavaScript. JSON dikirim dengan header Content-Type: application/json. Alternatifnya termasuk XML (besar, usang), YAML (nyaman untuk konfigurasi, jarang untuk API), dan Protocol Buffers (biner, efisien untuk sistem dengan beban tinggi).

Struktur objek JSON dalam REST API biasanya mencakup bidang id, type, dan atribut sumber daya. Untuk koleksi, digunakan array JSON dengan metadata paginasi. REST API modern mengikuti spesifikasi JSON:API (jsonapi.org) atau JSON Schema untuk validasi respons. Penggunaan format data yang seragam menyederhanakan pengembangan pustaka klien dan pembuatan dokumentasi.

Contoh respons JSON untuk daftar pengguna:

{
    "data": [
        {
            "id": 1,
            "name": "Anna Petrova",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

Pilihan format transmisi data memengaruhi kinerja aplikasi mobile. JSON dikompresi melalui GZIP sebesar 70–80%, membuatnya dapat diterima untuk sebagian besar skenario. Untuk aplikasi real-time dengan volume data besar (streaming, game), disarankan beralih ke protokol biner atau menggunakan WebSocket dalam kombinasi dengan Protocol Buffers.

Contoh permintaan REST API

Mari kita lihat contoh praktis bekerja dengan REST API di sisi aplikasi mobile. Sebagai contoh, kita ambil API untuk bekerja dengan pesanan di toko online. Untuk setiap metode HTTP, ditunjukkan permintaan dan respons server yang diharapkan. Contoh-contoh tersebut menunjukkan struktur tipikal RESTful API yang digunakan dalam pengembangan mobile.

GET — mendapatkan daftar pesanan

Permintaan untuk mendapatkan semua pesanan pengguna dengan paginasi. Respons berisi array objek pesanan dan meta-informasi untuk navigasi halaman. Parameter page dan per_page dikirim melalui query string.

// Antarmuka Retrofit untuk REST API
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — membuat pesanan baru

Membuat pesanan baru melalui permintaan POST. Server mengembalikan status 201 Created dan objek yang dibuat di tubuh respons. Penting: pembuatan dilakukan pada koleksi /api/v1/orders, bukan pada sumber daya tertentu — ini adalah pola RESTful standar.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// Contoh tubuh permintaan
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — menghapus pesanan

Penghapusan sumber daya dilakukan dengan metode DELETE pada URL spesifik pesanan. Penghapusan berhasil mengembalikan 204 No Content. Idempotensi DELETE berarti bahwa permintaan berulang ke URL yang sama akan mengembalikan 404 Not Found, yang ditangani dengan benar di sisi klien.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// Penggunaan di ViewModel
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

Contoh-contoh ini menunjukkan implementasi tipikal REST API di sisi Android menggunakan Retrofit dan Kotlin Coroutines. Untuk aplikasi iOS, peran serupa dimainkan oleh URLSession atau pustaka Alamofire dalam kombinasi dengan protokol Codable. Struktur REST API tetap sama terlepas dari platform — hanya cara eksekusi permintaan yang berubah.

Desain RESTful API: rekomendasi praktis

Merancang RESTful API berkualitas tinggi memerlukan kepatuhan terhadap konvensi yang membuat API intuitif bagi pengembang. Sumber daya harus dinamai dengan kata benda jamak (/users, /orders, /products), metode HTTP harus mencerminkan operasi, dan URL harus menunjukkan hierarki bersarang. Kesalahan harus mengembalikan JSON terstandarisasi dengan kode dan pesan, bukan hanya status HTTP. Kepatuhan terhadap konvensi ini menurunkan hambatan masuk bagi pengembang baru dan menyederhanakan integrasi.

• Penamaan sumber daya — jamak, kebab-case: /api/v1/user-orders, bukan /api/v1/getUserOrders
• Penyaringan dan pengurutan — melalui parameter query: ?status=active&sort=created_at:desc
• Paginasi — cursor-based untuk set besar, page-based untuk set kecil
• Versioning — melalui URL (/api/v2/) atau header Accept-Version
• Kesalahan — format seragam: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• Rate limiting — header X-RateLimit-Remaining dan Retry-After

Salah satu kesalahan umum dalam merancang REST API adalah penyarangan sumber daya yang berlebihan. Alih-alih /users/1/orders/5/items/3, lebih baik menggunakan struktur datar dengan parameter query: /items?order_id=5&user_id=1. Ini menyederhanakan caching, tidak memerlukan dukungan jalur panjang di server, dan lebih mudah didokumentasikan. Arsitektur datar juga lebih kompatibel dengan permintaan berbasis graph saat beralih ke GraphQL di masa depan.

Keamanan REST API diimplementasikan melalui autentikasi (JWT, OAuth 2.0) dan otorisasi di tingkat sumber daya. Setiap permintaan harus memeriksa apakah pengguna memiliki akses ke sumber daya yang diminta. HTTPS wajib — tanpa enkripsi, token dan data dikirim dalam teks biasa. Untuk aplikasi mobile, disarankan menggunakan OAuth 2.0 dengan PKCE (Proof Key for Code Exchange) untuk mendapatkan token dengan aman.

Versioning dan caching

Versioning REST API diperlukan untuk kompatibilitas mundur saat terjadi perubahan. Pendekatan yang paling umum: versi di URL (/api/v1/orders), versi di header (Accept: application/vnd.myapi.v1+json), dan versi di parameter query (?api_version=1). Versioning URL adalah metode paling populer karena terlihat jelas di log dan dokumentasi. Namun, ini melanggar prinsip REST tentang URL sumber daya yang unik.

Caching dalam REST API diimplementasikan melalui header HTTP Cache-Control, ETag, dan Last-Modified. Permintaan GET yang ditandai sebagai dapat di-cache dapat dilayani dari cache browser atau proxy tanpa menghubungi server. Untuk aplikasi mobile, caching sangat penting — ini mengurangi konsumsi bandwidth dan mempercepat tampilan data yang telah dimuat sebelumnya saat koneksi buruk. ETag adalah hash dari konten respons: klien mengirimkannya di If-None-Match, dan server mengembalikan 304 Not Modified jika data tidak berubah.

Alternatif modern untuk REST API termasuk GraphQL (pemilihan data yang fleksibel oleh klien) dan gRPC (protokol biner di atas HTTP/2 untuk mikrolayanan). Namun, REST tetap menjadi standar utama untuk API publik karena kesederhanaan, universalitas, dan dukungan alat yang luas. Pilihan antara REST dan alternatif tergantung pada persyaratan spesifik proyek: kompleksitas permintaan, volume data, persyaratan pembaruan real-time.