Intinya
Gunakan REST untuk API publik dan operasi CRUD sederhana. Gunakan GraphQL saat klien membutuhkan pengambilan data yang fleksibel dan Anda ingin mengurangi kelebihan pengambilan (over-fetching). Gunakan gRPC untuk komunikasi microservices berkinerja tinggi. Modern PetstoreAPI mengimplementasikan ketiga protokol tersebut, memungkinkan Anda memilih alat yang tepat untuk setiap kasus penggunaan.
Pendahuluan
Anda sedang membangun API. Haruskah Anda menggunakan REST, GraphQL, atau gRPC? Setiap protokol memiliki pendukung yang antusias mengklaim bahwa protokol mereka adalah yang terbaik. Kenyataannya: semuanya bagus untuk hal-hal yang berbeda.
REST bersifat universal dan sederhana. GraphQL memberi klien kendali atas pengambilan data. gRPC cepat dan efisien untuk layanan internal. Pilihan terbaik bergantung pada kasus penggunaan Anda, bukan protokol mana yang “lebih baik.”
Sebagian besar API memilih satu protokol dan tetap menggunakannya. Modern PetstoreAPI mengambil pendekatan yang berbeda: ini mengimplementasikan REST, GraphQL, dan gRPC, menunjukkan bagaimana API pet store yang sama bekerja di ketiga protokol tersebut.
Dalam panduan ini, Anda akan mempelajari kekuatan dan kelemahan masing-masing protokol, melihat contoh nyata dari Modern PetstoreAPI, dan menemukan cara memilih protokol yang tepat untuk kebutuhan Anda.
REST: Standar Universal
REST (Representational State Transfer) adalah protokol API yang paling umum.
Cara Kerja REST
Sumber daya diakses melalui URL dengan metode HTTP:
GET /pets - List pets
POST /pets - Create pet
GET /pets/{id} - Get pet
PUT /pets/{id} - Update pet
DELETE /pets/{id} - Delete pet
Contoh permintaan:
GET https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24
Contoh respons:
{
"id": "019b4132-70aa-764f-b315-e2803d882a24",
"name": "Fluffy",
"species": "CAT",
"status": "AVAILABLE",
"price": 299.99
}
Kelebihan REST
1. Kompatibilitas universal
Setiap bahasa pemrograman memiliki pustaka HTTP. Peramban, curl, Postman—semuanya berfungsi dengan REST.
2. Mudah dipahami
URL mewakili sumber daya. Metode HTTP mewakili tindakan. Model mentalnya lugas.
3. Dapat di-cache
Caching HTTP berfungsi secara langsung. Permintaan GET dapat di-cache oleh peramban, CDN, dan proxy.
4. Tanpa status (Stateless)
Setiap permintaan bersifat independen. Tidak ada status sesi di server.
5. Alat yang hebat
Spesifikasi OpenAPI, Swagger UI, alat pengujian API—REST memiliki ekosistem terbaik.
Kelemahan REST
1. Kelebihan pengambilan (Over-fetching)
Anda mendapatkan semua bidang meskipun Anda hanya membutuhkan satu:
// Anda hanya membutuhkan nama, tetapi Anda mendapatkan semuanya
{
"id": "019b4132-70aa-764f-b315-e2803d882a24",
"name": "Fluffy",
"species": "CAT",
"status": "AVAILABLE",
"price": 299.99,
"description": "...",
"images": [...],
"vaccinations": [...]
}
2. Kekurangan pengambilan (Under-fetching) (masalah N+1)
Untuk mendapatkan hewan peliharaan dan pesanannya, Anda memerlukan beberapa permintaan:
GET /pets/123 # Get pet
GET /pets/123/orders # Get orders
GET /orders/456/items # Get order items
3. Kompleksitas pembuatan versi
Perubahan yang merusak memerlukan versi API baru (/v1, /v2).
4. Tidak ada pembaruan real-time
REST adalah permintaan-respons. Untuk data real-time, Anda memerlukan polling atau WebSockets.
Kapan Menggunakan REST
- API Publik (kompatibilitas maksimum)
- Operasi CRUD sederhana
- Saat caching penting
- Saat Anda membutuhkan dukungan alat yang luas
- Aplikasi seluler dengan kebutuhan data yang dapat diprediksi
Implementasi REST Modern PetstoreAPI
GraphQL: Pengambilan Data yang Fleksibel
GraphQL memungkinkan klien menentukan dengan tepat data apa yang mereka butuhkan.
Cara Kerja GraphQL
Endpoint tunggal dengan bahasa kueri:
query {
pet(id: "019b4132-70aa-764f-b315-e2803d882a24") {
name
species
orders {
id
total
items {
product
quantity
}
}
}
}
Respons:
{
"data": {
"pet": {
"name": "Fluffy",
"species": "CAT",
"orders": [
{
"id": "order-123",
"total": 49.99,
"items": [
{"product": "Cat food", "quantity": 2}
]
}
]
}
}
}
Kelebihan GraphQL
1. Tidak ada kelebihan pengambilan (over-fetching)
Klien hanya meminta bidang yang mereka butuhkan:
query {
pet(id: "019b4132-70aa-764f-b315-e2803d882a24") {
name # Hanya ambil namanya
}
}
2. Tidak ada kekurangan pengambilan (under-fetching)
Dapatkan data terkait dalam satu permintaan:
query {
pet(id: "019b4132-70aa-764f-b315-e2803d882a24") {
name
orders {
items {
product
}
}
}
}
Tidak ada masalah N+1.
3. Tipe yang kuat (Strong typing)
Skema GraphQL memiliki tipe yang kuat. Klien tahu persis apa yang tersedia.
4. Introspeksi
Klien dapat mengkueri skema untuk menemukan operasi yang tersedia:
query {
__schema {
types {
name
fields {
name
type
}
}
}
}
5. Endpoint tunggal
Semua operasi melalui satu URL: /graphql
Kelemahan GraphQL
1. Kompleksitas
GraphQL lebih sulit dipelajari daripada REST. Kueri, mutasi, langganan, resolver—ada lebih banyak hal yang perlu dipahami.
2. Caching lebih sulit
Caching HTTP tidak berfungsi dengan baik. Anda memerlukan strategi caching kustom.
3. Risiko kueri berlebihan
Klien dapat menulis kueri yang mahal:
query {
pets {
orders {
items {
product {
reviews {
author {
pets {
# Kedalaman tak terbatas!
}
}
}
}
}
}
}
}
Anda memerlukan batasan kedalaman kueri dan analisis kompleksitas.
4. Pengunggahan file canggung
GraphQL tidak dirancang untuk pengunggahan file. Anda memerlukan solusi.
5. Pemantauan lebih sulit
Semua permintaan masuk ke /graphql. Anda tidak dapat memantau berdasarkan URL.
Kapan Menggunakan GraphQL
- Aplikasi seluler (mengurangi bandwidth)
- Kebutuhan data yang kompleks
- Saat klien membutuhkan fleksibilitas
- API internal dengan klien yang diketahui
- Saat Anda ingin menghindari pembuatan versi
Implementasi GraphQL Modern PetstoreAPI
gRPC: RPC Berkinerja Tinggi
gRPC menggunakan Protocol Buffers untuk komunikasi biner yang efisien.
Cara Kerja gRPC
Mendefinisikan layanan dalam file .proto:
service PetService {
rpc GetPet(GetPetRequest) returns (Pet);
rpc ListPets(ListPetsRequest) returns (ListPetsResponse);
rpc CreatePet(CreatePetRequest) returns (Pet);
}
message Pet {
string id = 1;
string name = 2;
string species = 3;
PetStatus status = 4;
}
Kode klien (yang dibuat):
client := pb.NewPetServiceClient(conn)
pet, err := client.GetPet(ctx, &pb.GetPetRequest{
Id: "019b4132-70aa-764f-b315-e2803d882a24",
})
Kelebihan gRPC
1. Kinerja
Protocol Buffers lebih kecil dan lebih cepat daripada JSON:
- Muatan 3-10x lebih kecil
- Serialisasi 20-100x lebih cepat
2. Streaming
Dukungan bawaan untuk streaming server, streaming klien, dan streaming dua arah:
rpc WatchPets(WatchPetsRequest) returns (stream Pet);
3. Tipe yang kuat (Strong typing)
Protocol Buffers menerapkan tipe pada waktu kompilasi.
4. Pembuatan kode
Hasilkan kode klien dan server dalam 10+ bahasa dari file .proto.
5. HTTP/2
Multiplexing, kompresi header, dan dorongan server.
Kelemahan gRPC
1. Tidak ramah peramban
Peramban tidak mendukung streaming dua arah HTTP/2. Anda memerlukan grpc-web (solusi).
2. Tidak dapat dibaca manusia
Protocol Buffers bersifat biner. Anda tidak dapat curl pada endpoint gRPC dan membaca responsnya.
3. Lebih sulit untuk di-debug
Protokol biner lebih sulit diperiksa daripada JSON.
4. Kurangnya alat
Lebih sedikit alat dibandingkan dengan REST. Tidak ada yang setara dengan Swagger UI.
5. Kurva pembelajaran yang lebih curam
Protocol Buffers, pembuatan kode, dan konsep gRPC membutuhkan waktu untuk dipelajari.
Kapan Menggunakan gRPC
- Komunikasi microservices
- Persyaratan kinerja tinggi
- Streaming real-time
- API internal (tidak publik)
- Lingkungan polyglot (berbagai bahasa)
Implementasi gRPC Modern PetstoreAPI
Perbandingan Berdampingan
| Fitur | REST | GraphQL | gRPC |
|---|---|---|---|
| Protokol | HTTP/1.1 atau HTTP/2 | HTTP/1.1 atau HTTP/2 | Hanya HTTP/2 |
| Format Data | JSON (umumnya) | JSON | Protocol Buffers (biner) |
| Endpoint | Banyak (/pets, /orders) |
Tunggal (/graphql) |
Metode layanan |
| Kelebihan Pengambilan | Umum | Jarang | N/A (Anda menentukan pesan) |
| Kekurangan Pengambilan | Umum (N+1) | Jarang | N/A |
| Caching | Sangat Baik (HTTP) | Buruk | Buruk |
| Dukungan Peramban | Sangat Baik | Sangat Baik | Buruk (membutuhkan grpc-web) |
| Alat | Sangat Baik | Baik | Cukup |
| Kurva Pembelajaran | Mudah | Menengah | Sulit |
| Kinerja | Baik | Baik | Sangat Baik |
| Streaming | Tidak (membutuhkan WebSocket) | Ya (langganan) | Ya (asli) |
| Pembuatan Versi | URL atau header | Evolusi skema | Evolusi proto |
| Terbaik Untuk | API Publik, CRUD | Klien fleksibel | Microservices |
Bagaimana Modern PetstoreAPI Mengimplementasikan Ketiganya
Modern PetstoreAPI unik: ia mengimplementasikan API pet store yang sama dalam REST, GraphQL, dan gRPC.
Data yang Sama, Tiga Protokol
Dapatkan hewan peliharaan berdasarkan ID:
REST:
GET https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24
GraphQL:
query {
pet(id: "019b4132-70aa-764f-b315-e2803d882a24") {
id
name
species
}
}
gRPC:
pet, err := client.GetPet(ctx, &pb.GetPetRequest{
Id: "019b4132-70aa-764f-b315-e2803d882a24",
})
Ketiganya mengembalikan data hewan peliharaan yang sama.
Mengapa Mengimplementasikan Ketiganya?
1. Belajar dengan perbandingan
Lihat bagaimana operasi yang sama bekerja dalam protokol yang berbeda.
2. Pilih alat yang tepat
Gunakan REST untuk endpoint publik, GraphQL untuk aplikasi seluler, gRPC untuk layanan internal.
3. Jalur migrasi
Mulai dengan REST, tambahkan GraphQL atau gRPC nanti tanpa menulis ulang semuanya.
4. Implementasi referensi
Modern PetstoreAPI menunjukkan pola siap produksi untuk ketiga protokol.
Periksa panduan perbandingan protokol untuk contoh rinci.
Menguji API Multi-Protokol dengan Apidog
Apidog mendukung REST, GraphQL, dan gRPC dalam satu alat.
Menguji REST
Impor spesifikasi OpenAPI dan jalankan pengujian otomatis:
pm.test("Status is 200", () => {
pm.response.to.have.status(200);
});
pm.test("Pet has required fields", () => {
const pet = pm.response.json();
pm.expect(pet).to.have.property('id');
pm.expect(pet).to.have.property('name');
});
Menguji GraphQL
Tulis kueri GraphQL dan validasi respons:
query GetPet($id: ID!) {
pet(id: $id) {
id
name
species
}
}
Apidog memvalidasi terhadap skema GraphQL.
Menguji gRPC
Impor file .proto dan uji layanan gRPC:
service: PetService
method: GetPet
request: { "id": "019b4132-70aa-764f-b315-e2803d882a24" }
Apidog menghasilkan permintaan dari definisi Protocol Buffer.
Pengujian Lintas Protokol
Uji bahwa ketiga protokol mengembalikan data yang konsisten:
- Panggil endpoint REST
- Panggil kueri GraphQL
- Panggil metode gRPC
- Bandingkan respons
Apidog membantu memastikan API multi-protokol Anda tetap konsisten.
Memilih Protokol yang Tepat
Gunakan pohon keputusan ini:
Apakah ini API publik?→ Ya: Gunakan REST (kompatibilitas maksimum) → Tidak: Lanjutkan
Apakah Anda memerlukan streaming real-time?→ Ya: Gunakan gRPC atau WebSocket → Tidak: Lanjutkan
Apakah klien membutuhkan pengambilan data yang fleksibel?→ Ya: Gunakan GraphQL → Tidak: Lanjutkan
Apakah kinerja sangat penting (microservices)?→ Ya: Gunakan gRPC → Tidak: Gunakan REST (opsi paling sederhana)
Contoh Dunia Nyata
- Stripe: REST (API publik, sederhana, dapat di-cache)
- GitHub: REST + GraphQL (REST untuk publik, GraphQL untuk kueri kompleks)
- Google Cloud: gRPC + REST (gRPC untuk kinerja, REST untuk kompatibilitas)
- Netflix: GraphQL (aplikasi seluler membutuhkan data yang fleksibel)
- Uber: gRPC (komunikasi microservices)
Bisakah Anda Menggunakan Beberapa Protokol?
Ya! Modern PetstoreAPI menunjukkan caranya. Pola umum:
- REST untuk API publik
- GraphQL untuk aplikasi seluler
- gRPC untuk microservices internal
Setiap protokol melayani klien yang berbeda dengan kebutuhan yang berbeda.
Kesimpulan
REST, GraphQL, dan gRPC bukanlah pesaing—mereka adalah alat untuk pekerjaan yang berbeda. REST bersifat universal dan sederhana. GraphQL memberi klien kendali. gRPC cepat dan efisien.
Modern PetstoreAPI mengimplementasikan ketiganya, menunjukkan bagaimana API yang sama bekerja di seluruh protokol. Anda dapat menjelajahi dokumentasi REST, skema GraphQL, dan file proto gRPC untuk melihat contoh siap produksi.
Gunakan Apidog untuk menguji ketiga protokol, membandingkan implementasi, dan memastikan konsistensi di seluruh API multi-protokol Anda.
Protokol terbaik adalah yang memecahkan masalah spesifik Anda. Modern PetstoreAPI memberi Anda pengetahuan untuk memilih dengan bijak.
FAQ
Bisakah saya menggunakan REST dan GraphQL bersama?
Ya. Banyak API menawarkan keduanya. Gunakan REST untuk operasi sederhana dan GraphQL untuk kueri kompleks. GitHub melakukan ini.
Apakah gRPC menggantikan REST?
Tidak. gRPC adalah untuk microservices internal. REST tetap menjadi standar untuk API publik karena kompatibilitas dan alat yang lebih baik.
Protokol mana yang tercepat?
gRPC adalah yang tercepat karena Protocol Buffers dan HTTP/2. Tetapi untuk sebagian besar API, perbedaannya tidak terlalu penting—latensi jaringan lebih dominan.
Haruskah saya bermigrasi dari REST ke GraphQL?
Hanya jika Anda memiliki masalah kelebihan pengambilan/kekurangan pengambilan (over-fetching/under-fetching). Jangan bermigrasi hanya karena GraphQL sedang tren.
Bisakah peramban menggunakan gRPC?
Tidak secara langsung. Anda memerlukan grpc-web, yang menambah kompleksitas. Untuk klien peramban, gunakan REST atau GraphQL.
Bagaimana Modern PetstoreAPI menjaga ketiga protokol tetap sinkron?
Lapisan logika bisnis bersama. REST, GraphQL, dan gRPC adalah adaptor protokol tipis di atas API inti yang sama.
Protokol mana yang harus digunakan startup?
Mulai dengan REST. Sederhana, mudah dipahami, dan memiliki alat yang hebat. Tambahkan GraphQL atau gRPC nanti jika Anda membutuhkannya.
Apakah Apidog mendukung ketiga protokol?
Ya. Apidog mendukung REST (OpenAPI), GraphQL, dan gRPC dalam satu alat, membuatnya mudah untuk menguji API multi-protokol seperti Modern PetstoreAPI.