Implementasi API Versioning di Laravel

Laravel API Version - Dalam pengembangan perangkat lunak modern, RESTful API (Application Programming Interface) telah menjadi sarana yang populer untuk berinteraksi dengan aplikasi melalui HTTP request. Dalam proses pengembangan aplikasi, mungkin terjadi perubahan dalam API yang dapat mempengaruhi client yang sudah ada. Oleh karena itu, API versioning atau penetapan versi API menjadi sangat penting untuk mengelola perubahan tersebut dengan cara yang tidak mengganggu client yang sudah ada.

Di lingkungan pengembangan Laravel, salah satu framework PHP paling populer, API versioning bisa diimplementasikan dengan berbagai cara, baik melalui URL, header request, atau melalui subdomain. Dalam artikel ini, kita akan menjelaskan berbagai pendekatan untuk melakukan versioning pada API di Laravel menggunakan URL.

Mengapa API Versioning Penting?

API versioning memungkinkan pengembang untuk membuat perubahan dalam API tanpa mempengaruhi fungsionalitas yang ada pada client yang sudah ada. Dengan API versioning yang baik, client dapat terus berfungsi sebagaimana mestinya bahkan jika ada pembaruan atau perubahan dalam API. Hal ini membantu untuk menghindari masalah kompatibilitas dan memastikan user experience yang lebih baik.

Salah satu contoh kasus nyata adalah ketika Kita membangun aplikasi mobile yang menggunakan API sebagai backend. Jika Kita merilis versi baru dari aplikasi mobile kita dengan perubahan di dalam API, tetapi API versi sebelumnya masih digunakan oleh beberapa user yang belum memperbarui aplikasinya, maka versi lama harus tetap dapat berfungsi agar user tersebut tidak mengalami masalah.

Implementasi API Versioning di Laravel

Ada beberapa cara untuk mengimplementasikan versioning pada API di Laravel. Di bawah ini adalah beberapa pendekatan yang umum digunakan:

1. URL Parameter

Salah satu cara paling sederhana untuk melakukan API versioning adalah dengan menyertakan nomor versi API sebagai bagian dari URL. Contoh URL dengan parameter versi API adalah sebagai berikut:

https://api.example.com/v1/posts

Ketika ada perubahan yang mempengaruhi versi API, Kita dapat membuat versi baru dengan URL yang berbeda, misalnya /v2/posts. Cient yang sudah ada akan tetap terhubung ke versi sebelumnya, sementara client baru dapat menggunakan versi terbaru.

2. Subdomain

Pendekatan lain untuk versioning adalah menggunakan subdomain. Anda dapat menyematkan nomor versi sebagai subdomain dalam URL API. Contoh:

https://v1.api.example.com/posts

Dengan menggunakan subdomain, Kita dapat dengan mudah memisahkan request antara versi API yang berbeda. Ini juga memberikan manfaat tambahan dalam hal cache dan konfigurasi server.

3. Header Request (Accept Header)

Pendekatan lain yang sering digunakan adalah menggunakan header request (misalnya, Accept header) untuk menyatakan versi API yang diinginkan. Cient dapat mengirimkan header Accept dengan nilai tertentu untuk menentukan versi API yang akan digunakan. Contoh:

GET /users HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.v1+json

Dalam contoh di atas, Cient mengirimkan header Accept dengan nilai application/vnd.example.v1+json untuk menunjukkan bahwa mereka ingin menggunakan versi 1 dari API.

4. Namespace di Laravel Route

Dalam framework Laravel, Kita juga dapat menggunakan fitur "Route Grouping" untuk mengelompokkan rute berdasarkan versi API. Dengan cara ini, Kita dapat dengan mudah menyimpan logika versi API yang berbeda dalam direktori yang terpisah. Contoh:

Route::prefix('v1')->group(function () {
    Route::get('users', [UserController::class], 'index');
    Route::post('users', [UserController::class], 'store');
});

Route::prefix('v2')->group(function () {
    Route::get('users', [UserController::class], 'index');
    Route::post('users',[UserController::class], 'store');
}); 

Selain dengan menggunakan fitur Route Grouping seperti contoh di atas, kita bisa menggunakan cara dengan memisahkan folder atau berdasarkan nama class. Nah, di artikel ini saya akan memberikan contohnya berdasarkan artikel-artikel yang publish sebelumnya pada serie Laravel 10 Sanctum.

Baca: Laravel 10 Rest API using Sanctum

Kita bisa melakukan konfigurasi di dalam method RouteServiceProvider::boot() seperti di bawah ini:

public function boot(): void
{
    ....
    ....
    ....
    $this->routes(function () {
        Route::middleware('api')
            ->prefix('api/v1')
            ->group(base_path('routes/api_v1.php'));
        ....
        ....
        ....
    });
}

Selanjutnya kita bisa membuat folder baru dengan nama V1 di dalam folder Http/Controllers/Api. Setelah folder V1 dibuat, kita pindahkan file PostController.php dan AuthController.php ke folder baru tersebut. Jika kedua file controller sudah dipindahkan ke folder V1, jangan lupa untuk update namespace.

Dari yang sebelumnya:

namespace App\Http\Controllers\Api;

Menjadi:

namespace App\Http\Controllers\Api\V1;

Kemudian kita bisa mengubah route file name dari api.php menjadi api_v1.php dan menyesuaikan controller path dari yang sebelumnya seperti di bawah ini:

use App\Http\Controllers\Api\AuthController;
use App\Http\Controllers\Api\PostController;

Menjadi seperti ini:

use App\Http\Controllers\Api\V1\AuthController;
use App\Http\Controllers\Api\V1\PostController;

Nah, sekarang jika kita jalankan perintah php artisan route:list, maka format endpoint sudah menjadi seperti di bawah ini.

POST            api/v1/login ........................................................................................................... Api\V1\AuthController@login
POST            api/v1/logout ......................................................................................................... Api\V1\AuthController@logout
POST            api/v1/otp ............................................................................................................... Api\V1\AuthController@otp
GET|HEAD        api/v1/posts ............................................................................................. posts.index › Api\V1\PostController@index
POST            api/v1/posts ............................................................................................. posts.store › Api\V1\PostController@store
GET|HEAD        api/v1/posts/{post} ........................................................................................ posts.show › Api\V1\PostController@show
PUT|PATCH       api/v1/posts/{post} .................................................................................... posts.update › Api\V1\PostController@update
DELETE          api/v1/posts/{post} .................................................................................. posts.destroy › Api\V1\PostController@destroy
GET|HEAD        api/v1/profile ....................................................................................................... Api\V1\AuthController@profile
POST            api/v1/profile ................................................................................................. Api\V1\AuthController@updateProfile
POST            api/v1/register ..................................................................................................... Api\V1\AuthController@register

Menangani Perubahan dan Deprecated API

Ketika merencanakan perubahan dalam API, penting untuk mempertimbangkan penghapusan fitur (deprecated) yang sudah ada pada versi sebelumnya. Kita dapat memberikan pemberitahuan atau pesan khusus kepada pengembang dan pengguna tentang perubahan yang akan datang dan kapan fitur lama akan dihapus.

Selain itu, pastikan untuk menyediakan dokumentasi yang jelas dan lengkap tentang perubahan apa saja yang terjadi dalam setiap versi API, sehingga user dapat dengan mudah beralih ke versi baru tanpa mengalami kesulitan.

Kesimpulan

API versioning merupakan praktek yang penting dalam pengembangan aplikasi berbasis API untuk mengelola perubahan dengan baik tanpa mengganggu klien yang sudah ada. Dalam framework Laravel, terdapat berbagai cara untuk melakukan versioning, mulai dari penggunaan URL parameter dan subdomain hingga header request.

Memilih pendekatan yang tepat tergantung pada kebutuhan proyek dan preferensi tim pengembang. Yang terpenting adalah memastikan bahwa perubahan dalam API dikelola dengan baik dan didokumentasikan dengan jelas untuk memudahkan pengguna dalam beradaptasi dengan perubahan tersebut.

Published on July 30, 2023
Last updated on June 03, 2026