Pengenalan JSON-RPC part 2

Setelah berkenalan dengan apa itu JSON-RPC di post sebelumnya, sekarang mari kita coba berkenalan lebih jauh, yaitu bagaimana spesifikasi dari JSON-RPC itu sendiri. Berhubung saat ini JSON-RPC sudah memasuki versi 2.0, maka yang akan kita bahas yaitu JSON-RPC 2.0.

Sesuai dengan namanya, JSON-RPC menggunakan format JSON sebagai format datanya.

Request Object

Request pada JSON-RPC terdiri dari 4 (empat) buah properti, dimana properti-properti tersebut BOLEH tidak berurutan, yaitu:

• jsonrpc – string yang menunjukkan versi JSON-RPC yang digunakan. Properti ini bersifat WAJIB dan nilainya HARUS “2.0″.
• method – string yang menunjukkan nama method yang akan dipangil.
• params – array yang berisi object-object yang menjadi parameter dari method yang akan dipanggil.
• id – string/number/null yang merupakan identifier unik untuk setiap JSON-RPC request yang membutuhkan response. Apabila request object tidak memiliki properti id, maka request tersebut akan dianggap sebagai notification.

Coba kita lihat kembali request object pada post sebelumnya.

{
    "id":"123456abcd",
    "jsonrpc":"2.0",
    "method":"findPersonByName",
    "params":["Herloct"]
}

Pada request object di atas, dapat dilihat bahwa client ingin memanggil method bernama findPersonByName dengan menggunakan parameter “Herloct”. Anggap saja di server ada service seperti ini

<?php

class PersonService
{
    public function findPersonByName($name)
    {
        // $list berisi array dari PersonVo
        $list = array();

        // ambil dari database berdasarkan nama lalu masukkan hasilnya ke dalam $list
        // kalau $list kosong, maka tampilkan pesan error.
        if (count($list) == 0)
            throw new Exception("Cannot find Person with name '$name'.", 101);

        return $list;
    }
}
class PersonVo
{
    public $name;
    public $age;
}

Response Object

Response pada JSON-RPC terdiri dari 4 (empat) buah properti, yaitu:

• jsonrpc – sama seperti pada request object.
• result – properti yang HARUS ada jika pemanggilan method berhasil. Properti ini HARUS bernilai null apabila pemanggilan method menghasilkan error. Isi dari properti ini tergantung dari nilai kembalian method yang dipanggil oleh request objet.
• error – properti yang HARUS ada jika pemanggilan method menghasilkan error. Properti ini HARUS bernilai null apabila pemanggilan method berhasil tanpa menghasilkan error. Properti ini akan dibahas lebih lanjut di error object.
• id – properti ini HARUS ada dan memiliki nilai yang sama dengan properti id pada request object.

Coba kita lihat kembali response object pada post sebelumnya.

{
    "id":"123456abcd",
    "jsonrpc":"2.0",
    "error":null,
    "result":[
        {
            "name":"Herloct",
            "age":8,
        }, {
            "name":"Captain Herloct",
            "age":56,
        }, {
            "name":"Herloct HENT",
            "age":23,
        }
    ]
}

Pada response object di atas, dapat dilihat bahwa pemanggilan method findPersonByName berhasil tanpa error. Berhubung method tersebut mengembalikan nilai array, maka yang akan tampil pada response object > result juga berbentuk JSON array. Properti error bernilai null menandakan bahwa pemanggilan method tidak menghasilkan error.

Lalu bagaimana jika method itu menghasilkan error?

Disinilah kita membutuhkan yang namanya Error Object. Error Object ini akan mengisi properti error pada response object. Error Object terdiri dari 3 (tiga) buah properti, yaitu:

• code – integer number yang menunjukkan tipe error yang muncul.
• message – string yang menunjukkan pesan errornya.
• data – merupakan data tambahan sebagai detil dari error yang dihasilkan. Properti ini BOLEH ada maupun tidak. Isinya bisa berupa Object, number, string, maupun array, disesuaikan dengan kebutuhan.

Pada kelas PersonService, apabila tidak ada orang yang bernama “Herloct”, maka akan menghasilkan error berupa “Cannot find person with name ‘Herloct’”. Maka response object yang akan dihasilkan adalah.

{
    "id":"123456abcd",
    "jsonrpc":"2.0",
    "result":null,
    "error":{
        "code":-101,
        "message":"Cannot find Person with name 'Herloct'."
    }
}

Berikut merupakan error code yang reserved oleh JSON-RPC.

code	message	keterangan
-32700	Parse error	Terjadi error ketika server mem-parsing JSON object dari client.
-32600	Invalid Request	Request object yang dikirim tidak valid.
-32601	Method not found	Method yang dipanggil tidak ada.
-32602	Invalid params	Parameter yang dimasukkan tidak valid/tidak sesuai dengan method yang dipanggil.
-32603	Internal error	Internal JSON-RPC error.
-32099 to -32000	Server error	Reserved untuk keperluan implementasi JSON-RPC lainnya. (jujur saya juga belum ngerti ini maksudnya apa)

Spesifikasi lengkap dari JSON-RPC dapat dilihat di http://groups.google.com/group/json-rpc/web/json-rpc-2-0.

Hmm, rasanya hambar banget yah, kalo ga pake contoh implementasi benerannya. Pada pertemuan selanjutnya, akan saya coba berikan contoh implementasinya menggunakan PHP sebagai server dan jQuery sebagai client-nya.

Saya juga mau minta maaf sebelumnya jika post saya masih berantakan…

Advertisement