Desain API

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:

1. 1XX
   • Respon yang sifatnya informasi saja. (Kita tidak memakainya untuk projek kali ini)
2. 2XX
   • Respon sukses, beberapa kode yang akan dipakai: 200 (ok), 201 (created), 202 (Accepted), 204 (No content)
3. 3XX
   • Respon sukses, masalah redirect, akan anda dialihkan ke url lain.
4. 4XX
   • Respon gagal, kesalahan dari client. Kode yang dipakai: 401 (Unauthorized), 403 (Forbidden) 404 (Not Found), 409 (coflict)
5. 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.

Menambahkan blog baru

POST /posts

success

{
  "success": {
    "status": 201, 
    "message": "new post was created"
  }
}

error

{
  "error": {
    "status": 409, 
    "message:" "new post was not created"
  }
}

Melihat koleksi dari semua data blog

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": []

Melihat individual data blog

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"
}

Mengupdate individual data blog

PUT /post/1

sucess

"success": {
  "status": 200,
  "message": "post was successfully updated"
}

error

"error": {
  "status": 409, 
  "message": "post was not updated" 
}

Menghapus individual data blog

DELETE /post/1

success

"success": {
  "status": 200, 
  "message": "post was successfully deleted"
}

error

"error": {
  "status": 409, 
  "message": "post was not deleted"
}

Otentikasi

Login

POST /auth

success

"success": {
  "status": 200, 
  "message": "you were authenticated"
}

error

"error": {
  "status": 409, 
  "message": "username or password is not wrong"
}

Logout

DELETE /auth

success

"success": {
  "status": 200, 
  "message": "you sucessfully to logout"
}

error

"error": {
  "status": 409, 
  "message": "you fail to logout"
}

Otorisasi

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.