Desain yang berorientasi pada sumber daya

Tujuan Panduan Desain ini adalah untuk membantu developer mendesain API jaringan yang sederhana, konsisten, dan mudah digunakan. Pada saat yang sama, fitur ini juga membantu menggabungkan desain RPC berbasis soket dengan REST API berbasis HTTP.

RPC API sering kali didesain dari segi antarmuka dan metode. Seiring bertambahnya metode tersebut dari waktu ke waktu, hasil akhirnya dapat menjadi platform API yang berlebihan dan membingungkan karena developer harus mempelajari setiap metode secara terpisah. Tentu saja hal ini memakan waktu dan rawan kesalahan.

Gaya arsitektur REST diperkenalkan, terutama dirancang agar berfungsi dengan baik dengan HTTP/1.1, sekaligus membantu mengatasi masalah ini. Prinsip utamanya adalah menentukan resource bernama yang dapat dimanipulasi menggunakan sejumlah kecil metode. Resource dan metode ini dikenal sebagai kata benda dan kata kerja API. Dengan protokol HTTP, nama resource secara alami dipetakan ke URL, dan metode dipetakan secara alami ke metode HTTP POST, GET, PUT, PATCH, dan DELETE. Hal ini menghasilkan hal yang jauh lebih sedikit untuk dipelajari, karena developer dapat berfokus pada resource dan hubungannya, serta menganggap bahwa mereka memiliki jumlah metode standar yang sama sedikit.

Di Internet, HTTP REST API telah sangat berhasil. Pada tahun 2010, sekitar 74% API jaringan publik adalah API REST HTTP (atau mirip REST), yang sebagian besar menggunakan JSON sebagai format berkabel.

Meskipun HTTP/JSON API sangat populer di Internet, jumlah traffic yang dibawa lebih kecil daripada RPC API tradisional. Misalnya, sekitar setengah dari traffic Internet di Amerika pada waktu puncak adalah konten video, dan hanya sedikit orang yang akan mempertimbangkan menggunakan HTTP/JSON API untuk menayangkan konten tersebut untuk alasan performa yang jelas. Di dalam pusat data, banyak perusahaan menggunakan RPC API berbasis soket untuk membawa sebagian besar traffic jaringan, yang dapat melibatkan urutan data yang jauh lebih banyak (diukur dalam byte) daripada API HTTP/JSON publik.

Pada kenyataannya, RPC API dan HTTP/JSON API diperlukan karena berbagai alasan, dan idealnya, platform API harus memberikan dukungan terbaik untuk semua jenis API. Panduan Desain ini membantu Anda mendesain dan membangun API yang sesuai dengan prinsip ini. Hal ini dilakukan dengan menerapkan prinsip desain berorientasi resource ke desain API umum dan menentukan banyak pola desain umum untuk meningkatkan kegunaan dan mengurangi kompleksitas.

Apa itu REST API?

REST API dimodelkan sebagai koleksi resource yang dapat ditangani satu per satu (kata benda API). Resource direferensikan dengan nama resource-nya dan dimanipulasi melalui sekumpulan kecil metode (juga dikenal sebagai kata kerja atau operasi).

Metode standar untuk REST Google API (juga dikenal sebagai metode REST) adalah List, Get, Create, Update, dan Delete. Metode kustom (juga dikenal sebagai kata kerja kustom atau operasi kustom) juga tersedia bagi desainer API untuk fungsi yang tidak mudah dipetakan ke salah satu metode standar, seperti transaksi database.

Alur desain

Panduan Desain menyarankan untuk mengambil langkah-langkah berikut saat mendesain API berorientasi resource (detail selengkapnya dibahas di bagian spesifik di bawah):

Tentukan jenis resource yang disediakan API.
Menentukan hubungan antar-sumber daya.
Tentukan skema nama resource berdasarkan jenis dan hubungan.
Tentukan skema resource.
Melampirkan kumpulan metode minimum ke resource.

Referensi

API berorientasi resource umumnya dimodelkan sebagai hierarki resource, dengan setiap node merupakan resource sederhana atau resource koleksi. Untuk memudahkan, keduanya sering disebut sebagai resource dan koleksi.

Koleksi berisi daftar resource dari jenis yang sama. Misalnya, pengguna memiliki kumpulan kontak.
Resource memiliki beberapa status dan nol atau beberapa sub-resource. Setiap sub-resource dapat berupa resource sederhana atau resource koleksi.

Misalnya, Gmail API memiliki sekumpulan pengguna. Setiap pengguna memiliki sekumpulan pesan, sekumpulan thread, sekumpulan label, resource profil, dan beberapa resource setelan.

Meskipun ada beberapa keselarasan konseptual antara sistem penyimpanan dan REST API, layanan dengan API berorientasi resource belum tentu merupakan database, dan memiliki fleksibilitas yang sangat besar terkait cara menafsirkan resource dan metode. Misalnya, membuat acara kalender (fasilitas) dapat membuat acara tambahan untuk peserta, mengirim undangan email kepada peserta, mereservasi ruang konferensi, dan memperbarui jadwal konferensi video.

Metode

Karakteristik utama dari API berorientasi resource adalah bahwa API ini menekankan resource (model data) daripada metode yang dijalankan pada resource (fungsi). API standar berorientasi resource mengekspos sejumlah besar resource dengan sedikit metode. Metode tersebut dapat berupa metode standar atau metode kustom. Untuk panduan ini, metode standarnya adalah: List, Get, Create, Update, dan Delete.

Jika fungsi API secara alami dipetakan ke salah satu metode standar, metode tersebut harus digunakan dalam desain API. Untuk fungsi yang tidak dipetakan secara alami ke salah satu metode standar, metode kustom dapat digunakan. Metode kustom menawarkan kebebasan desain yang sama seperti RPC API tradisional, yang dapat digunakan untuk menerapkan pola pemrograman umum, seperti transaksi database atau analisis data.

Contoh

Bagian berikut menampilkan beberapa contoh nyata tentang cara menerapkan desain API berorientasi resource ke layanan berskala besar. Anda dapat menemukan contoh lainnya di repositori Google API.

Dalam contoh ini, tanda bintang menunjukkan satu sumber daya tertentu dari daftar.

Gmail API

Layanan Gmail API menerapkan Gmail API dan mengekspos sebagian besar fungsi Gmail. Class ini memiliki model resource berikut:

Layanan API: gmail.googleapis.com
- Kumpulan pengguna: users/*. Setiap pengguna memiliki referensi berikut.
  - Kumpulan pesan: users/*/messages/*.
  - Kumpulan rangkaian pesan: users/*/threads/*.
  - Kumpulan label: users/*/labels/*.
  - Kumpulan histori perubahan: users/*/history/*.
  - Resource yang mewakili profil pengguna: users/*/profile.
  - Resource yang mewakili setelan pengguna: users/*/settings.

Cloud Pub/Sub API

Layanan pubsub.googleapis.com menerapkan Cloud Pub/Sub API, yang menentukan model resource berikut:

Layanan API: pubsub.googleapis.com
- Kumpulan topik: projects/*/topics/*.
- Kumpulan langganan: projects/*/subscriptions/*.

Cloud Spanner API

Layanan spanner.googleapis.com mengimplementasikan Cloud Spanner API, yang menentukan model resource berikut:

Layanan API: spanner.googleapis.com
- Kumpulan instance: projects/*/instances/*. Setiap instance memiliki resource berikut.
- Kumpulan operasi: projects/*/instances/*/operations/*.
- Kumpulan database: projects/*/instances/*/databases/*. Setiap database memiliki resource berikut.
  - Kumpulan operasi: projects/*/instances/*/databases/*/operations/*.
  - Kumpulan sesi: projects/*/instances/*/databases/*/sessions/*.