API adalah antarmuka pemrograman untuk komunikasi antara aplikasi atau komponen. API dibagi menjadi pribadi dan publik. API pribadi digunakan dalam perusahaan jika, misalnya, memiliki beberapa produk perangkat lunak yang berkomunikasi satu sama lain. API publik dapat digunakan oleh pengembang pihak ketiga. Benar, dalam beberapa kasus Anda harus membayarnya. Tetapi kemudian persyaratan pengguna untuk kualitas dan kegunaan API juga akan lebih tinggi.
Ketika layanan API menjadi publik, tidak ada keajaiban yang terjadi. Jumlah pengguna tidak bertambah, dan Anda biasanya dapat melupakan membuat fungsi ini berbayar (kami mengecualikan kasus ketika produk dipromosikan karena pemasaran terletak pada iklan agresif).
Dan jika pendapatan perusahaan secara langsung bergantung pada API publik, maka taruhannya sangat tinggi. Ide ini dibahas lebih detail dalam buku “API Continuous Development. Keputusan yang tepat dalam lanskap teknologi yang berubah ”(Mehdi Medjui, Ronnie Mitra, dll.):
dan kami akan melangkah lebih jauh ...
Pengembang terutama dapat fokus untuk mengimplementasikan semua fungsionalitas yang direncanakan di API. Tetapi ada persyaratan "non-fungsional" yang seringkali tidak sepenuhnya terpenuhi dan memerlukan perhatian khusus.
Menurut pendapat saya, untuk semua API, persyaratan non-fungsional berikut harus dipenuhi dengan kualitas yang baik:
- Keamanan
- Dokumentasi
- Validasi
- Pengujian
Keamanan
Mungkin tidak ada gunanya menjelaskan mengapa keselamatan didahulukan. Saya telah mengidentifikasi empat tantangan keamanan yang paling penting:
- Menggunakan HTTPS dengan Sertifikat SSL
- Berbagi Sumber Daya dari Berbagai Sumber (CORS)
- Otentikasi dan Token Web JSON
- Otorisasi dan hak akses
* Selanjutnya, kita akan mempersempit konteksnya menjadi REST dan JSON API.
1. Menggunakan HTTPS dengan sertifikat SSL
HTTPS yang menggunakan sertifikat SSL sekarang menjadi standar keamanan de facto. Untuk membuat sertifikat, saya pribadi menggunakan Let's Encrypt , CA otomatis gratis dari Internet Security Research Group (ISRG) nirlaba.
Sertifikat ini memastikan bahwa data yang masuk dari API Anda ke pengguna dienkripsi.
2. Berbagi sumber daya dari berbagai sumber (CORS)
Untuk menjaga keamanan permintaan ke sumber lain, browser menggunakan mekanisme yang disebut CORS. CORS adalah singkatan dari Cross-Origin Resource Sharing, sebuah teknologi untuk berbagi sumber daya dari berbagai sumber. Meskipun browser (berdasarkan aturan sumber yang sama) tidak mengizinkan akses ke sumber daya dari sumber yang berbeda, CORS memungkinkan Anda untuk melewati batasan ini dan pada saat yang sama memastikan bahwa akses ke sumber daya aman.
Agen pengguna (misalnya, browser), berdasarkan nilai header tambahan untuk CORS dalam permintaan HTTP, dapat membuat permintaan ke sumber lain yang akan diblokir tanpa CORS.
Berikut ini contohnya :
Halaman HTML yang dilayani oleh server dari http://domain-a.com meminta src di http://domain-b.com/image.jpg .
Banyak halaman memuat sumber daya seperti gaya CSS, gambar, dan skrip dari domain berbeda yang sesuai dengan CDN (Jaringan Pengiriman Konten) yang berbeda.
Implementasi CORS untuk Node.js cukup populer saat ini .
3. Otentikasi dan Token Web JSON (JWT)
Ada beberapa pendekatan untuk otentikasi pengguna API, tetapi salah satu yang terbaik adalah menggunakan JWT. Token ini ditandatangani menggunakan berbagai algoritma kriptografi.
JSON Web Token adalah standar terbuka untuk membuat token akses berdasarkan format JSON. Biasanya digunakan untuk melewatkan data otentikasi dalam aplikasi client-server.
Untuk membuat token, Anda perlu menentukan header dengan informasi umum tentang token, payload, seperti id pengguna, peran, dan sebagainya, serta tanda tangan. Secara sederhana, JWT hanyalah sebuah string dalam format berikut header.payload.signature.
Ketika klien log on, layanan manajemen identitas menyediakan JWT ke klien. Klien kemudian dapat menggunakan token ini untuk membuat permintaan API. API memiliki akses ke kunci publik atau rahasia yang digunakannya untuk memvalidasi token.
Untuk verifikasi, Anda dapat menggunakan, misalnya, perpustakaan jsonwebtoken . Di bawah ini adalah kode JavaScript:
import jwt from 'jsonwebtoken'
export default function (req, res, next) {
// req.headers.authorization Bearer token
const token = extractToken (req)
jwt.verify (token, SECRET, {algorithms: ['HS256']}, (err, diterjemahkan) => {
the if (err) {next (err)}
req.session = Decoded
next ()
})
}
Informasi lebih lanjut tentang JWT, perpustakaan, dan bahasa pemrograman yang didukung - JWT.io online .
4. Otorisasi dan hak akses
Otentikasi itu penting, tetapi otorisasi sama pentingnya: apakah klien yang mengautentikasi dan menerima JWT memiliki hak istimewa untuk mengeksekusi permintaan tertentu?
Untuk menguji ini, kami menggunakan ruang lingkup. Dengan menganalisisnya, layanan API menentukan apakah permintaan klien ini dapat dipenuhi tanpa pencarian ACL yang mahal.
Cakupan adalah blok teks (biasanya dipisahkan oleh spasi) yang menjelaskan hak akses titik akhir API. Ini menjelaskan Sumber Daya dan Tindakan yang dapat diterapkan padanya. Formalisasi ini bekerja dengan baik untuk REST / JSON API karena strukturnya sangat mirip.
RESOURCE: ACTION (misalnya, ARTICLE: WRITE atau ARTICLE: READ, di mana ARTICLE adalah resource dan READ and WRITE adalah tindakan).
Ini memungkinkan pengembang API untuk fokus pada fitur daripada peran atau pengguna. Layanan manajemen identitas dapat mengaitkan peran dan pengguna dengan cakupan tertentu, dan kemudian, bersama dengan JWT, mengirim cakupan ke klien.
Untuk tidur dengan tenang
Saat mengembangkan dan menerapkan API, keamanan harus selalu menjadi salah satu persyaratan terpenting. Tentu saja, Anda dapat berbicara dan menulis tentangnya tanpa henti, tetapi implementasi yang kompeten dari empat tugas yang dijelaskan dalam produksi akan memungkinkan Anda untuk tidur nyenyak.
Dokumentasi
Apa yang bisa lebih buruk daripada kurangnya dokumentasi? Dokumentasi usang!
Pengembang ambigu tentang dokumentasi. Banyak yang jelas tidak memiliki banyak cinta untuk bisnis ini. Bagaimanapun, tugas ini sangat penting - terutama dalam hal API publik. Pengembang pihak ketiga harus dapat mempelajari cara menggunakannya. Plus, dokumentasi yang baik akan membantu Anda melatih pengembang baru yang bergabung dengan tim Anda lebih cepat.
Dokumentasi API harus mencakup tiga bagian dasar:
- Pendahuluan (README)
- Lembar Data (Spesifikasi)
- Contoh penggunaan (Memulai dan subbagian serupa lainnya)
1. BACA SAYA
Dokumentasi harus memberi tahu Anda tentang kegunaan API, cara menyiapkan lingkungan, cara menguji layanan, cara menerapkan proyek. Tentu saja, pengguna juga perlu mengetahui bagaimana dan di mana melaporkan kesulitan atau masalah.
Ini ditulis dalam file README. File ini biasanya juga ditempatkan di repositori, ini memberi pengembang titik awal untuk bekerja dengan proyek Anda.
README harus berisi:
- Deskripsi API
- Tautan ke referensi dan manual teknis
- Panduan penyiapan pengembang
- Panduan Penguji
- Panduan Penerapan
- Manajemen ketergantungan
- Panduan Kontributor
- Kode etik
- Lisensi
- Terima kasih
Singkat dalam README Anda; Anda tidak perlu menjelaskan semua nuansa, tetapi berikan informasi yang cukup bagi pengembang untuk menyelami proyek Anda.
2. Spesifikasi
Di REST / JSON API, setiap titik akhir adalah fungsi yang dibangun untuk tujuan tertentu. Penting untuk memiliki dokumentasi teknis yang menjelaskan setiap titik akhir, input dan output, dan bagaimana layanan bekerja dengan klien yang berbeda.
Anda dapat membuat dokumentasi API Anda sendiri berdasarkan OpenAPI .
Ini adalah spesifikasi dan kerangka kerja lengkap untuk mendeskripsikan, membuat, menggunakan, dan merender layanan web REST. Tugasnya adalah mengizinkan sistem dokumentasi untuk menyinkronkan pembaruannya dengan perubahan di server. Metode, parameter, model, dan elemen lainnya terintegrasi dengan perangkat lunak server melalui OpenAPI dan disinkronkan dengannya setiap saat.
3. Contoh penggunaan
Pengguna API Anda tidak akan senang jika Anda hanya membuang spesifikasi pada mereka. Mereka ingin tahu cara menggunakan API Anda dalam situasi tertentu dan cara memecahkan masalah umum. Sebagian besar calon pengguna memiliki masalah dan mereka beralih ke API Anda untuk menyelesaikannya.
Cara yang bagus untuk memperkenalkan pengguna ke API Anda adalah dengan membuat subbagian Memulai. Ini akan membantu Anda memahami kasus penggunaan umum dan menggunakannya untuk mengevaluasi manfaat API Anda.
Tiga paus
Dokumentasi adalah komponen kunci dari API apa pun. Saat menulis dokumentasi, ingatlah tiga pilar dokumentasi API yang berhasil - README, spesifikasi, dan kasus penggunaan. Dan Anda (dan pengguna Anda) akan senang!
Validasi data
Aspek penting dari pengembangan API, validasi data, sering diabaikan oleh banyak orang. Validasi adalah proses memvalidasi input dari sumber eksternal. Sumber-sumber ini dapat berupa klien yang mengirim JSON atau layanan yang menanggapi permintaan Anda. Pemeriksaan ini akan memastikan bahwa data persis seperti yang seharusnya. Berkat itu, Anda dapat menghilangkan banyak masalah potensial. Tugas penting validasi adalah memahami format apa dan rentang nilai apa yang harus dimiliki data input dan bagaimana mengontrolnya.
Strategi terbaik adalah menjalankan validasi sebelum layanan Anda melakukan manipulasi data apa pun. Saat klien mengirim data mereka ke API Anda, seperti email, tanggal, dan nama, pastikan itu benar-benar alamat email, tanggal diformat dengan benar, dan string memenuhi persyaratan panjang. Pemeriksaan sederhana ini akan membuat layanan Anda lebih aman dan teratur.
Juga, ketika Anda mendapatkan data dari suatu layanan, dari beberapa jenis database atau cache, periksa kembali untuk memastikan hasil yang dikembalikan seperti yang diharapkan.
Anda dapat menerapkan validasi secara manual, tetapi perpustakaan seperti Lodash atau Ramda juga dapat digunakan untuk tujuan ini .... Mereka bagus untuk objek data kecil. Pustaka seperti Joi , Yup, atau Zod bekerja lebih baik karena memungkinkan Anda menjelaskan kerangka validasi umum, menghemat waktu dan tenaga Anda. Jika Anda membutuhkan sesuatu yang independen dari bahasa pemrograman tertentu, lihat Skema JSON .
Lebih baik jauhkan
Validasi hampir tidak menarik, tetapi dapat menghemat banyak waktu yang seharusnya dihabiskan untuk memecahkan masalah dan menulis skrip migrasi data. Jangan membuat kesalahan dengan memercayai klien Anda untuk mengirim data yang belum diverifikasi jika Anda tidak ingin data yang buruk berakhir di logika atau penyimpanan bisnis Anda.
Luangkan waktu dan atur validasi untuk masukan Anda. Seperti kata pepatah, lebih baik berlebihan daripada melewatkannya.
Pengujian
Pengujian merupakan bagian integral dari siklus hidup perangkat lunak. Dalam kasus kami, itu harus dianggap sebagai salah satu persyaratan non-fungsional utama. Mendefinisikan strategi pengujian bisa menjadi tugas yang menakutkan untuk proyek apa pun, termasuk API layanan. Selalu mencoba untuk menyadari keterbatasan Anda dan menentukan strategi Anda sesuai.
Pengujian integrasi adalah salah satu metode pengujian API yang paling efektif. Tugasnya adalah memverifikasi bahwa aplikasi bertransisi dengan benar dari satu status ke status lainnya. Dalam kasus kami, rangkaian pengujian integrasi harus mencakup pengujian titik masuk API layanan, serta maket untuk mensimulasikan pengiriman permintaan ke sana dan menerima respons. Inilah cara kami memeriksa kasus uji utama layanan kami.
Metode ini memungkinkan Anda untuk fokus hanya pada logika pemrosesan data, tanpa mempertimbangkan internal layanan backend atau logika presentasi data. Kurangnya ketergantungan membuat eksekusi pengujian lebih andal, lebih mudah untuk diotomatisasi, dan lebih mudah untuk dimasukkan ke dalam pipa integrasi berkelanjutan.
Untuk pengujian integrasi, saya menggunakan Tape , Test-server dan Fetch-mock . Pustaka ini memungkinkan Anda menjalankan pengujian terisolasi terhadap titik akhir API, mulai dari permintaan hingga respons.
permainan imitasi
Jenis pengujian dan pemeriksaan jenis lainnya tentu saja berguna juga, dengan pengujian integrasi memiliki keuntungan terbesar: sangat efisien dengan lebih sedikit jam kerja yang dihabiskan untuk menulis dan memelihara pengujian. Dan menggunakan alat seperti Fetch-mock dapat memberikan simulasi pertukaran data yang lengkap.
Jangan berhenti di situ
Setelah Anda menyelesaikan keempat persyaratan non-fungsional, jangan berhenti di situ. Ada beberapa lagi: pemantauan aplikasi, logging, dan manajemen API. Tetapi bagaimanapun juga, keamanan, dokumentasi, validasi, dan pengujian harus diutamakan.
Server cloud dari Macleod cepat dan aman.
Daftar menggunakan tautan di atas atau dengan mengklik spanduk dan dapatkan diskon 10% untuk bulan pertama menyewa server dengan konfigurasi apa pun!
