API, Web Service, & RESTful API

o API
API (Application Programming Interface), adalah sebuah interface yang berperan untuk
mengintegrasikan dua bagian dari aplikasi atau dengan aplikasi yang berbeda secara
bersamaan agar kedua bagian tersebut bisa berkomunikasi satu sama lain. API terdiri dari
berbagai elemen seperti function, protocols, dan tools lainnya yang memungkinkan
developers untuk membuat aplikasi. Tujuan penggunaan API adalah untuk mempercepat
proses development dengan menyediakan function secara terpisah sehingga developer
tidak perlu membuat fitur yang serupa.

o Web Service
Pada dasarnya Web Service adalah API, namun interaksi antara kedua mesin melewati
suatu jaringan. Biasanya “HTTP” adalah protocol yang paling banyak dipakai untuk
berkomunikasi. Web service biasa bertipe SOAP atau REST. Sedangkan API bisa memakai
semua tipe untuk menjalankan komunikasi.

o RESTful API
RESTful API adalah API (termasuk web service) yang menerapkan konsep metode REST,
di mana REST itu kependakan dari REpresentational State Transfer yang merupakan standar
arsitektur berbasis web yang menggunakan protokol HTTP untuk berkomunikasi data. REST
merupakan standar arsitektur komunikasi berbasis web yang sering diterapkan dalam
pengembangan layanan berbasis web, menggantikan SOAP di tahun 2000, setelah
diperkenalkan oleh Roy Fielding. Kelebihan dari REST adalah
 light weight
SDK atau framework tidak diperlukan
lebih sederhana/simpel untuk dikembangkan ketimbang SOAP
 highly scalable
Tidak store the state ke memory, hanya perlu load balancer untuk ngebagi load
The server end of REST is stateless, which means that the server doesn't have to
store anything across requests. This means that there doesn't have to be (much)
communication between servers, making it horizontally scalable.
 maintainable

Arsitektur REST API

 Cara kerja RESTful API adalah REST client akan mengakses data/resource ke REST
server dimana masing-masing resource atau data tersebut dibedakan oleh sebuah global ID
atau URIs (Universal Resource Identifiers).

o JSON
JSON adalah format pertukaran data yang ringan, mudah dibaca dan ditulis. JSON
merupakan format teks yang tidak bergantung pada bahasa pemprograman apapun karena
menggunakan gaya bahasa yang umum digunakan oleh programmer keluarga C termasuk C,
C++, C#, Java, JavaScript, Perl, Python dll. Oleh karena sifat-sifat tersebut, menjadikan JSON
ideal sebagai bahasa pertukaran-data, dan umum digunakan dalam pertukaran data /
komunikasi api saat ini.
Karakteristik JSON :
 Mudah melakukan read dan write JSON
 lightweight text-based interchange format
 JSON tidak bergantung pada bahasa pemrograman
Contoh :
{
"books": [
 {
"id":"01",
"language": "Java",
"edition": "third",
"author": "Herbert Schildt"
},

{
"id":"07",
"language": "C++",
"edition": "second",
"author": "E.Balagurusamy"
}
]
}

o Method
Dalam penerapan REST, ada method yang digunakan untuk membedakan kegunaan dari
satu URI.

Pada umumnya, ada 4 method yang biasa digunakan, yaitu

Get -> read
Put -> update
Post -> create
Delete -> delete
 Berikut penjelasannya
 GET
Method GET dipakai untuk meng-inquiry data / informasi. Request GET
umumnya bersifat idempotent artinya walaupun dilakukan hit berulang kali
dengan parameter yang sama akan selalu menghasilkan response yang sama.
 POST
Method POST digunakan untuk sebuah request yang tujuannya untuk
melakukan sesuatu terhadap entity yang diakses. Umumnya POST digunakan
untuk meng-create entity baru, tetapi POST juga dapat digunakan untuk meng-
update sebuah entity. Method POST bersifat non-idempotent artinya jika
dilakukan request berulang-ulang kali menggunakan parameter yang sama,
maka akan dihasilkan response yang berbeda.
 PUT
Hampir sama dengan Method POST, Method PUT dapat digunakan untuk
melakukan create atau update terhadap sebuah entity. Perbedaannya adalah
method PUT bersifat idempotent yaitu multiple requests dengan parameter
yang sama akan menghasilkan response yang selalu sama.
PUT melakukan replace terhadap entity existing. Jika hanya sebagian element
data yang terisi, maka element data yang lain akan terisi dengan null.
 DELETE
Method Delete digunakan untuk menghapus resource yang dituju. Method
DELETE bersifat non-idempotent.
 PATCH
Fungsi Method PATCH hampir sama dengan method PUT atau POST, yaitu untuk
meng-update resource. Perbedaan pada method PATCH yaitu PATCH dapat
digunakan untuk melakukan update atau modifikasi partial / sebagian pada
resource. Sehingga pada request PATCH, tidak perlu dituliskan seluruh element
dari resource yang akan di-update, cukup tuliskan element yang akan diupdate.
Method PATCH bersifat non-idempotent.
 HEAD
Method HEAD hampir sama dengan method GET, hanya saja response dari
HEAD tidak akan menghasilkan response body. Method GET hanya akan
mengembalikan HTTP Code 200 jika resource yang dicari tersedia. Method
HEAD dapat digunakan untuk mengecek apakah resource tersedia sebelum
melakukan request dengan method GET. Method HEAD bersifat idempotent.

o URI
Dalam REST, representasi data disebut Resource. Salah satu komponen penyusun
pemanggilan request rest adalah URI (Uniform Resource Identifiers). URI digunakan untuk
memberi alamat pada resource. URI yang baik akan dapat mudah dimengerti dan mudah
dipakai.
 Resource bisa berupa singleton atau collection
Contohnya,
  “/customers” untuk resource bertipe collection
 “/customer” untuk resource bertipe singleton
 “/customers/{customerId}” juga bisa mengidentifikasi single customer

 Resource bisa mengandung sub-collection resource

 “/Customers/{customerId}/phones” untuk mengakses sub-collection
 “/Customers/{customerId}/phones/{phoneId}” untuk mengakses
singleton dari sub-collection
 Gunakan kata benda (noun) untuk melambangkan resource
http://api.example.com/users/{id}
 Consistency is the key
 Forward Slash(/) untuk menunjukan relasi hierarki
o http://api.example.com/device-management
o http://api.example.com/device-management/managed-devices
o http://api.example.com/device-management/managed-
devices/{id}
o http://api.example.com/device-management/managed-
devices/{id}/scripts
o http://api.example.com/device-management/managed-
devices/{id}/scripts/{id}
 Jangan gunakan trailing forward slash (/) pada URI
o Karena (/) adalah salah satu komponen penyusun URI, sehingga
akan menjadi path yang berbeda dan membingungkan, dan juga
tidak menambahkan value apa – apa.
 http://api.example.com/device-management/managed-
devices/
 http://api.example.com/device-management/managed-
devices /*This is much better version*/
 Gunakan hyphens (-) untuk mempermudah pembacaan URI
o http://api.example.com/inventory-management/managed-
entities/{id}/install-script-location //More readable
o http://api.example.com/inventory-
management/managedEntities/{id}/installScriptLocation //Less
readable
 Gunakan lowercase pada URI
o http://api.example.org/my-folder/my-doc //1
o HTTP://API.EXAMPLE.ORG/my-folder/my-doc //2
o http://api.example.org/My-Folder/my-doc //3

contoh diatas menunjukan nomor 1 dan 2 sama karena yang

berbeda adalah URL homenya, sedangkan nomor 3 beda, karena di
pathnya dia memakain “My-Folder”, bukan “my-folder” yang
merupakan 2 folder berbeda.
  Jangan gunakan fungsi CRUD pada URI
o X http://api.example.com/device-management/managed-
devices/get-all-devices
o -> HTTP GET http://api.example.com/device-
management/managed-devices
 Jangan gunakan underscores (_) juga untuk mempermudah pembacaan
o http://api.example.com/inventory-management/managed-
entities/{id}/install-script-location //More readable
o http://api.example.com/inventory_management/managed_enti
ties/{id}/install_script_location //More error prone
 Jangan pakai file extension dalam URI
o http://api.example.com/device-management/managed-
devices.xml /*Do not use it*/
o http://api.example.com/device-management/managed-devices
/*This is correct URI*/
 Gunakan query component untuk memfilter URI berjenis collection
o http://api.example.com/device-management/managed-devices
o http://api.example.com/device-management/managed-
devices?region=USA
o http://api.example.com/device-management/managed-
devices?region=USA&brand=XYZ
o http://api.example.com/device-management/managed-
devices?region=USA&brand=XYZ&sort=installation-date
 Selengkap bisa lihat di
 https://restfulapi.net/resource-naming/
 Path Param
Path Param digunakan untuk menunjukkan category atau identity dari sebuah
resource. Sebagai contoh untuk meng-inquiry SELURUH account statement dari
corporate h2hauto009 dengan rekening 0380101246 maka digunakan path param
seperti berikut:
http://api.example.com/banking/corporates/h2hauto009/accounts/038010124
6/statements
 Query Param

o Header
Komponen penyusun REST lainnya adalah Header Param. Header Param merupakan
parameter yang terdapat pada request header. Biasanya parameter ini digunakan untuk
menampung informasi terkait autorisasi dan format yang dipakai antara client dan server.
 Header param tersusun dari Key-Value. Di mana biasanya ada Key-Value
bawaan yang umum dipakai adalan Content-Type – application/json
 Ada banyak type yang lain, dan jenis key yang lain.
 Header param menggunakan hyphens(-) untuk pemisah per katanya. Serta tiap
awal kata menggunakan huruf kapital
  Kita dapat membuat header param custom, namun biasanya kita menambahi X
di depan key nya. Contohnya adalah X-Client-Id.
o Body
Komponen penyusun terakhir REST adalah Body. Body biasanya bersifat opsional,
biasanya pada saat kita akan mengirim, seperti mendaftar akun, update akun, dan lain –
lain. Body juga diterima sebagai response dari request REST.
 Body menggunakan format JSON.
 Karena menggunakan format JSON, biasanya format namingnya adalah
snake_case, yaitu huruf kecil dan menggunakan underscore untuk pemisahnya.
 Namun ada pula kasus tertentu yang menggunakan kebab-case atau spinal-case,
yaitu huruf kecil dengan hyphens sebagai pemisah kata, atau UpperCamelCase
dan camelCase, yang menggunakan huruf capital sebagai pemisah kata. seperti
beberapa REST dari EAI.
o HTTP Status
Tiap response dari pemanggilan satu request, pasti akan memiliki HTTP Status yang
menandakan kondisi dari response tersebut.
 200 = Success
 201 = Created
 400 = Bad Request
 403 = forbidden
 404 = not found
 504 = Timeout
 500 = Internal Server Error