Tulisan ini dibuat sebagai panduan dalam menulis kode API yang baik.
API adalah sebuah seni. Layaknya workflow dalam menulis kode, setiap orang memiliki caranya masing-masing dalam menulis kode API. Walapun berbeda namun tetap punya satu tujuan, API harus mudah dipelajari atau digunakan dan bersih.
Desain API yang akan dibuat akan mengimplementasikan konsep REST API. Jadi sebelum masuk ke pembahasan, akan menjelaskan REST API terlebih dahulu.
REST API adalah sebuah konsep untuk membuat API atau url menjadi bersih. Konsep REST API mengenalkan tiga method baru, yaitu PUT/PATCH dan DELETE. Penggunaannya dapat dilihat sebagai berikut:
- GET
/posts
- Menampilkan detail dari semua data post
- GET
/post/1
- Menampilkan detail data post dengan id = 1
- POST
/posts
- Menambah data post baru
- PUT/PATCH
/post/1
- Memperbaharui post baru dengan id = 1
- DELETE
/post/1
- Menghapus data post dengan id = 1
Dengan Konsep diatas anda tidak perlu menggunakan url /posts/getAll
atau /posts/createNew
dimana url tersebut terlihat kotor.
Selain itu kita akan membahas kode status yang menjadi respon atas request dari url yang baru saja dibahas.
HTTP pada dasarnya mempunyai empat jenis kode status, antara lain:
- 1XX
- Respon yang sifatnya informasi saja. (Kita tidak memakainya untuk projek kali ini)
- 2XX
- Respon sukses, beberapa kode yang akan dipakai: 200 (ok), 201 (created), 202 (Accepted), 204 (No content)
- 3XX
- Respon sukses, masalah redirect, akan anda dialihkan ke url lain.
- 4XX
- Respon gagal, kesalahan dari client. Kode yang dipakai: 401 (Unauthorized), 403 (Forbidden) 404 (Not Found), 409 (coflict)
- 5XX
- Respon gagal, kesalahan dari server atau programmernya. Bisanyanya mengembalikan kode status 500.
Setelah mengetahui konsep dasar dari REST API dan beberapa kode dari htpp status, maka kita melanjutkannya ke studi kasus. Studi kasus adalah API pada sebuah website blog.
POST /posts
success
{
"success": {
"status": 201,
"message": "new post was created"
}
}
error
{
"error": {
"status": 409,
"message:" "new post was not created"
}
}
GET /posts
success
"posts":[
{
"post":{
"title": "Ichigo da bes",
"description": "sample text"
}
},
{
"post":{
"title": "zero two is not bad",
"description": "another sample text"
}
}
]
if data not found
"posts": []
GET /post/1
success
"post": {
"title": "Non non biyori anime",
"description": "10/10 to good anime"
}
error
"error": {
"status": 204,
"message": "post is not found"
}
PUT /post/1
sucess
"success": {
"status": 200,
"message": "post was successfully updated"
}
error
"error": {
"status": 409,
"message": "post was not updated"
}
DELETE /post/1
success
"success": {
"status": 200,
"message": "post was successfully deleted"
}
error
"error": {
"status": 409,
"message": "post was not deleted"
}
POST /auth
success
"success": {
"status": 200,
"message": "you were authenticated"
}
error
"error": {
"status": 409,
"message": "username or password is not wrong"
}
DELETE /auth
success
"success": {
"status": 200,
"message": "you sucessfully to logout"
}
error
"error": {
"status": 409,
"message": "you fail to logout"
}
DELETE /post/1
error if not authenticate
"error": {
"status": 401,
"message": "Please login, you ware unauthenticated"
}
error if not authorization
"error":{
"status": 403,
"message": "Sorry, you have not permission to do this"
}
Sekian.