Menentukan Path, Kode Status, Header, Query String, dan Format Data


Masih dalam tahap persiapan, pada tulisan ini akan ditentukan format data yang akan dikembalikan ke aplikasi klien. Format data ini nantinya akan dijadikan sebagai acuan untuk jenis data lainnya. Tak hanya format data, beberapa respons seperti HTTP code dan headers juga akan diatur dalam aplikasi. Konsistensi format data memberikan kemudahan bagi aplikasi klien ketika mengkonsumsi API yang kita buat.

Indeks User

Untuk data indeks, kode HTTP yang dikembalikan adalah 200 (OK). Dikarenakan jumlah datanya bisa mencapai ribuan, maka alangkah baiknya jika data user dikembalikan dalam bentuk pagination. Berikut adalah contoh bentuk data pagination yang menampilkan 5 halaman untuk sekali request.

Endpoint indeks user dapat diakses melalui path /user dengan method GET.

{
    "current_page": 1,
    "data": [
        {
            "id": 1,
            "name": "Ms. Anais Green",
            "email": "swisozk@hotmail.com",
            "created_at": "2017-11-22 13:52:21",
            "updated_at": "2017-11-22 13:52:21"
        },
        {
            "id": 2,
            "name": "Mazie Okuneva MD",
            "email": "stokes.dorothea@mills.biz",
            "created_at": "2017-11-22 13:52:21",
            "updated_at": "2017-11-22 13:52:21"
        },
        {
            "id": 3,
            "name": "Dr. Lucius Heathcote",
            "email": "kleffler@hotmail.com",
            "created_at": "2017-11-22 13:52:21",
            "updated_at": "2017-11-22 13:52:21"
        },
        {
            "id": 4,
            "name": "Mariam Thiel",
            "email": "rahsaan.schaden@yahoo.com",
            "created_at": "2017-11-22 13:52:21",
            "updated_at": "2017-11-22 13:52:21"
        },
        {
            "id": 5,
            "name": "Elenora Bednar",
            "email": "kole.sipes@hilpert.info",
            "created_at": "2017-11-22 13:52:21",
            "updated_at": "2017-11-22 13:52:21"
        }
    ],
    "from": 1,
    "last_page": 21,
    "next_page_url": "http:\/\/localhost:8001\/user?page=2",
    "path": "http:\/\/localhost:8001\/user",
    "per_page": 5,
    "prev_page_url": null,
    "to": 5,
    "total": 102
}

Endpoint untuk mendapatkan indeks user juga menerima query string untuk penyaringan data. Adapun query yang dapat diterima adalah keyword. Query string keyword ini nantinya akan digunakan untuk melakukan pencarian berdasar name atau email pada tabel users.

Tak hanya keyword, endpoint juga menerima query string dengan nama limit yang berguna untuk menentukan jumlah data yang ditampilkan dalam satu kali request. Contoh penulisan di URL adalah sebagai berikut.

/user?keyword=anne&limit=10

Detail User

Menampilkan detail user berdasarkan parameteryang disematkan pada path. Tipe parameter path adalah integer yang merupakan id user terdaftar di pangkalan data. Apabila id tidak ditemukan, maka API akan mengembalikan respons berisi pesan kalau data user tidak ditemukan.

Endpoint detail user dapat diakses pada path /user/{id} dengan method GET.

Contoh apabila data user ditemukan. Perhatikan pada contoh data di bawah, kita tetap menggunakan key “data” sebagai root untuk menampung informasi user.

{
    "data": {
        "id": 1,
        "name": "Ms. Anais Green",
        "email": "swisozk@hotmail.com",
        "created_at": "2017-11-22 13:52:21",
        "updated_at": "2017-11-22 13:52:21"
    }
}

Apabila data user tidak ditemukan, API mengembalikan data dengan informasi kalau user dan tidak ditemukan. Dan paling penting, juga mengembalikan kode HTTP berupa 404 (Not Found).

{
    "status": 404,
    "message": "User not found with ID 11111.",
    "data": []
}

Sisipan/Buat User

Untuk menyisipkan data user yang bar juga dimungkinkan melalui API. Format data kembaliannya tidak berbeda dengan detail user. Hanya saja, kode HTTP diset menjadi 201 apabila data user berhasil disisipkan.

Endpoint sisipan data user dapat diakses pada path /user dengan method POST. Header dari aplikasi klien sendiri dapat berjenis application/x-www-form-urlencoded atau multipart/form-data.

{
    "data": {
        "name": "Dedy Yugo Purwantos",
        "email": "dedy.yugo.purwantos@gmail.com",
        "updated_at": "2017-11-22 14:15:31",
        "created_at": "2017-11-22 14:15:31",
        "id": 102
    }
}

Dalam proses sisipan data user, juga ditambahkan validasi untuk memastikan data yang akan disimpan benar-benar sudah bersih. Apabila data tidak valid, maka kode HTTP yang dikembalikan adalah 422 (Unprocessable Entity) dan menampilkan pesan kesalahn validasi.

{
    "name": [
        "The name field is required."
    ],
    "email": [
        "The email field is required."
    ],
    "password": [
        "The password field is required."
    ]
}

Perbarui User

Proses pembaruan data user ini kombinasi detail dan pembuatan user. Yang mana, pada path diperlukan parameter id yang digunakan untuk melakukan pencarian, kemudian mengirim paramater dalam format form seperti pembuatan user.

Endpoint pembaruan user dapat diakses pada path /user/{id} dengan methode PUT.

Respons data dikembalikan degan format sama persis dengan detail user, hanya saja data yang dikembalikan sudah diperbarui.

{
    "data": {
        "id": 2,
        "name": "Mazie Okuneva MD",
        "email": "stokes.dorothea@mills.biz",
        "created_at": "2017-11-22 13:52:21",
        "updated_at": "2017-11-22 13:52:21"
    }
}

Dalam proses pembaruan user juga terdapat validasi data input yang tak jauh berbeda dengan sisipan user.

Hapus User

Format data kembalian hapus user sama persin dengan detail user. Dalam proses hapus pun, datanya tetap dikembalikan sebagai informasi yang dapat diolah kembali di sisi aplikasi klien.

Endpoint hapus user dapat diakses pada /user/{id} dengan method DELETE.

{
    "data": {
        "id": 3,
        "name": "Dr. Lucius Heathcote",
        "email": "kleffler@hotmail.com",
        "created_at": "2017-11-22 13:52:21",
        "updated_at": "2017-11-22 13:52:21"
    }
}

Apabila user tidak ditemukan, maka akan mengembalikan pesan kesalahan yang sama dengan detail user.

{
    "status": 404,
    "message": "User not found with ID 3000.",
    "data": []
}

Nah, sampai di sini, rancangan format data, query string, path, method, sampai dengan format data sudah dijabarkan dengan cukup jelas. Masih satu langkah lagi sebelum menulis skrip proses CRUD di atas, yaitu membuat test untuk menguji aplikasi.

Pengujian nantinya mencakup beberapa hal, seperti URL yang sudah bisa diakses dan kesesuaian format data yang dikembalikan oleh API.

Tak Berkategori

Yugo Purwanto

Pemrogram PHP dan JavaScript yang sedang sibuk mengembangkan aplikasi Glosarium Bahasa Indonesia.

Tinggalkan Balasan