Membuat API Blueprint dengan apiary.io | Season 2

Pada tutorial sebelumnya kita telah membuat API dengan metode GET dan POST. Nah, pada tutorial kali ini kita akan membahas untuk mengubah (Update) dengan menggunakan metode PUT/PATCH dan menghapus data menggunakan metode DELETE. Kalian bisa membaca Season 1 dibawah ini.

Membuat API Blueprint dengan apiary.io | Season 1

“three persons in front of table” by rawpixel on Unsplash

PATCH

Untuk merubah data kita dapat menggunakan metode PATCH atau PUT. Nah, dalam kasus yang saya gunakan dalam penulisan ini menggunakan PATCH. Lalu, apa perbedaan dari PATCH dan PUT tersebut?

PUT digunakan untuk mengubah keseluruhan data (all fields). Contoh, dari beberapa data json dibawah ini menunjukkan value awal yang akan kita ubah type-nya menjadi kontrak.

{
  "name": "Fathur Rohim",
  "email": "rohim@dot-indonesia.com",
  "phone": "081388878676",
  "type": "Tetap",
  "image_url": "https://www.oimtrust.com/assets/img/oim.jpg"
}
// Di ubah menggunakan PUT
{
  "name": "Fathur Rohim",
  "email": "rohim@dot-indonesia.com",
  "phone": "081388878676",
  "type": "Kontrak",
  "image_url": "https://www.oimtrust.com/assets/img/oim.jpg"
}

PATCH digunakan untuk mengubah beberapa data (a few fields). Contoh, menggunakan data di atas (PUT) dan kita ubah dengan value yang sama namun dengan menggunakan metode PATCH.

{
  "type": "Kontrak"
}

Baiklah, dari kesimpulan saya yang sederhana ini semoga bisa dipahami. Melanjutkan dari source code yang telah kita tulis di season 1 sebelumnya, tambahkan source code berikut dibawah ### Create Profile.

### Update A Profile [PATCH]
- Request (application/json)
- Attributes (Profile)
- Response 201 (application/json)
- Attributes (Profile)
        - type : Kontrak

Lalu lihatlah hasilnya seperti gambar berikut :

Demo perubahan data dengan menggunakan PATCH Method

Nah, mudah bukan? Sekarang coba kalian buatlah perubahan data menggunakan metode PUT.

Selanjutnya adalah bagaimana ketika ketika melakukan perubahan data yang tidak valid? Pasti akan mengalami error, bukan? Yup… Mari kita ubah source code tersebut untuk membuat successfull updated dan unsuccessfull updated seperti berikut ini.

## Profile Resource [/profile/{id}]
### Update A Profile [PATCH]
- Request Successfull Update (application/json)
- Attributes (Profile Update Valid)
- Response 201 (application/json)
- Attributes (Profile)
        - type : Kontrak
        
- Request Unsuccessfull Update (application/json)
- Attributes (Profile Update Invalid)
    
- Response 422 (application/json)
- Attributes (Error Unprocessable Entity)
        - message : `This was an invalid type, please select Tetap, Freelance or Kontrak`
        - attribute : type

Lalu pada # Data Structurestambahkan source code berikut ini :

## Profile Update Valid
- type : Kontrak
## Profile Update Invalid
- type : `Tidak Tetap`
## Error Unprocessable Entity
- title : Unprocessable Entity
- message : This resource could not be updated due to invalid arguments being passed

Sehingga hasilnya menjadi seperti berikut ini.

DELETE

Untuk melakukan perubahan data telah selesai kita buat. Langkah terakhir adalah membuat perintah untuk menghapus data menggunakan metode DELETE. Yup, pembahasan kali ini menurut saya tidak terlalu asing bagi teman-teman. Lalu, seperti apakah penulisan source code yang akan kita buat? Ikutilah source code sederhana untuk menghapus data di bawah ini setelah ### Update A Profile.

### Delete A Profile [DELETE]
- Response 204

Lalu pada ## Profile Resource [/profile/{id}] tambahkan parameter seperti berikut ini.

## Profile Resource [/profile/{id}]
- Parameters
    - id : 6c34a6af-752d-408a-b5d3-00a368e7201e

Sehingga hasilnya menjadi seperti berikut ini :

Demo untuk metode DELETE

Nah, mudah bukan pembuatan untuk menghapus data? Selanjutnya silahkan kalian pelajari lagi dengan berbagai macam design API sesuai dengan apa yang kalian butuhkan untuk mematangkan pemahaman kalian.

Documentations

Secara tidak langsung, API Blueprint yang telah kita buat telah menjadi sebuah dokumentasi API yang rapi dan mudah sekali untuk dibaca. Alangkah lebih bagusnya kita detailkan lagi dengan penjelasan atribut-atributnya. Tambahkan beberapa source code berikut :

// Tambahkan attribute pada Profile Collection dan Profile Resource
- Attributes (Profile)

Sehingga nanti hasilnya didapat seperti gambar berikut :

Untuk source code lengkapnya bisa kalian lihat disini :

Source Code dari API Blueprint dengan apiary.io

Demikian tulisan season 2 ini. Nantikan season 3 untuk mocking API agar bisa di akses dan digunakan oleh Mobile Engineer dan atau engineer-engineer yang lain. Bila ada saran dan masukkan jangan sungkan untuk memberikan komentar agar tulisan saya bisa di perbaiki di artikel-artikel yang akan saya tulis lagi di kemudian hari.

Apabila kalian suka dengan artikel ini saya harap kalian berkenan memberikan claps dan share artikel ini agar bermanfaat bagi engineer yang lain. Terima Kasih.

Referensi

Documentation | API Blueprint

API Blueprint Specification | API Blueprint

HTTP Status Dogs

Follow Me on Twitter

Fathur Rohim (@oimtrust) | Twitter