2. API

Kami mengharapkan vendor perisian untuk mencipta mekanisme yang mana data boleh diperoleh semula secara digital daripada aplikasi. Ini melanjutkan usaha kami sebagai organisasi untuk menyediakan perkhidmatan kerjasama dan menggunakan data yang perkhidmatan kami kumpulkan dengan baik.

2.1 Mendokumenkan API anda

API perlu didokumenkan supaya berguna. Dokumentasi yang baik akan membolehkan pengguna API untuk bersepadu secara pantas dengan perkhidmatan tersebut dan memberi nilai.

Kami mencadang untuk menggunakan panduan di sini untuk mendapatkan idea tentang seksyen yang perlu disertakan apabila memformulasikan panduan anda.

2.2 Gunakan REST

Ikuti standard industri dan di mana sesuai bina API sesuai yang RESTful, menggunakan permintaan kata kerja HTTP untuk memanipulasikan data.

Apabila mengendalikan permintaan, anda perlu menggunakan kata kerja HTTP untuk tujuan yang ditentukan.

Salah satu kelebihan REST ialah ia memberi anda rangka kerja untuk menyampaikan keadaan ralat.

Dalam sesetengah keadaan, ia mungkin tidak boleh digunakan untuk membina REST API, sebagai contoh, apabila anda membina API untuk menstrim data.

Anda boleh membaca lebih lanjut tentang ciri-ciri bagi menggunakan RESTful API untuk tujuan penyepaduan perkhidmatan dalam dokumentasi MAMPU di sini.

2.3 Gunakan HTTPS

Anda perlu menggunakan HTTPS apabila mencipta API.

Penambahan HTTPS akan mengukuhkan sambungan ke API anda, mengekalkan privasi pengguna, memastikan integriti data, dan mengesahkan pelayan yang memberikan API. Manual Perkhidmatan memberikan lebih banyak panduan tentang HTTPS.

Kukuhkan API menggunakan Keselamatan Lapisan Pengangkutan (TLS) 1.2 atau lebih. Jangan gunakan Lapisan Soket Selamat (SSL), TLS 1.0 atau TLS 1.1 kerana ini tidak diluluskan.

Terdapat pelbagai vendor percuma dan kos rendah yang menawarkan pensijilan TLS. Pastikan pengguna API yang berpotensi boleh mewujudkan kepercayaan dalam persijilan anda dan pastikan anda mempunyai proses yang kukuh untuk pembaharuan dan pembatalan persijilan yang tepat pada masanya.

2.4 Gunakan JSON

Jika boleh, pilihan pertama anda untuk semua API web mestilah JSON.

Hanya gunakan perwakilan lain untuk mewujudkan sesuatu dalam keadaan berkecuali, seperti apabila anda:

perlu bersambung ke sistem legasi, sebagai contoh, yang menggunakan XML sahaja
akan menerima kelebihan yang jelas daripada pematuhan standard yang diterima pakai secara meluas (sebagai contoh, SAML)

Kami mengesyorkan supaya anda:

mencipta respons sebagai objek JSON dan bukan tatasusunan (objek JSON boleh mengandungi tatasusunan JSON) - tatasusunan boleh mengehadkan keupayaan untuk merangkumkan metadata tentang keputusan dan mengehadkan keupayaan API untuk menambah kunci tahap atas tambahan pada masa depan
dokumenkan pengembalian API anda kepada objek JSON. Ini membantu pengguna API anda untuk memastikan ia menggunakan objek tersebut dengan cara yang betul
elakkan kunci objek JSON yang tidak konsisten untuk semua objek bagi jenis yang sama, seperti yang diperoleh daripada data kerana ini menambah pergeseran untuk pelanggan
gunakan kasus tatabahasa yang konsisten untuk kunci objek – pilih di bawah skor (cth 'email_address': 'example@example.com') or camel case (cth. 'emailAddress': 'example@example.com') dan jadilah konsisten

2.5 Menstandardkan format tarikh / masa

Ia membantu apabila menggunakan RFC3339 standard untuk melambangkan tarikh dan masa dalam respons payload anda. Ini membantu orang ramai membaca masa dengan betul.

Gunakan format tarikh yang konsisten. Bagi tarikh, ini kelihatan seperti 2017-08-09. Bagi tarikh dan masa, gunakan bentuk 2017-08-09T13:58:07Z or 2017-08-09 13:58:07Z.

2.6 Gunakan Unikod untuk pengekodan

Standard Format Transformasi Unikod (UTF-8) digunakan oleh banyak badan kerajaan apabila mengekod teks atau perlambangan teks data yang lain.

2.7 Simpan log permintaan untuk data peribadi

Jika API anda memberikan khidmat peribasi atau data sensitif, anda perlu melog apabila data diberikan dan kepada siapa data diberikan. Ini akan membantu anda memastikan ‘privasi dengan reka bentuk’ dalam penghantaran perkhidmatan.

2.8 Masa untuk Mengesahkan API anda

Pengesahan diperlukan apabila anda ingin mengenal pasti pelanggan untuk tujuan:

pengehadan/pendikitan kadar
pengauditan
pengebilan
pengesahan

Tujuan anda akan mengimlakkan keperluan keselamatan untuk penyelesaian pengesahan anda.

Sebagai contoh, jika anda perlu mengenal pasti pengguna semata-mata untuk pengehadan kadar, anda mungkin tidak perlu untuk menyegarkan semula token dengan terlalu kerap kerana token dalam tangan yang salah tidak mungkin mengancam perkhidmatan anda.

2.9 Bagi memberikan pengesahan tahap aplikasi

Gunakan pengesahan tahap aplikasi jika anda ingin mengawal jenis aplikasi yang boleh mengakses API, tetapi bukan pengguna akhir tertentu. Ini sesuai jika anda ingin melaksanakan pengehadan kadar, pengauditan, atau fungsi pengebilan. Pengesahan tahap aplikasi mungkin tidak sesuai untuk API yang akan memegang data peribadi atau sensitif melainkan anda benar-benar mempercayai pengguna akhir, sebagai contoh, jabatan lain dalam organisasi yang sama.

Kami mengesyorkan supaya menggunakan OAuth 2.0, rangka kerja pengesahan terbuka (khususnya dengan jenis geran Butiran Kelayakan Pelanggan). Perkhidmatan ini memberikan OAuth2 Bearer Token kepada setiap permohonan berdaftar, yang boleh digunakan untuk melakukan permintaan API bagi pihak aplikasi itu sendiri.

2.10 Bagi memberikan pengesahan tahap pengguna

Gunakan pengesahan tahap pengguna jika anda ingin mengawal pengguna akhir yang boleh mengakses API anda. Ini sesuai untuk berurusan dengan data peribadi atau sensitif.

Kami mengesyorkan penggunaan OAuth 2.0, rangka kerja pengesahan terbuka (khususnya dengan jenis geran Kod Pengesahan). Gunakan OAuth 2.0 Scopes untuk lebih banyak kawalan akses granul.

Dalam persekitaran yang lebih kompleks seperti perkhidmatan mikro atau sistem bersekutu OpenID Connect, yang dibina di atas OAuth 2.0 menggunakan JSON Web Tokens (JWT), juga mungkin lebih sesuai. OpenID Connect memberikan mekanisme granul dan yang boleh dibaca oleh mesin untuk meminta dan menerima maklumat tentang sesi yang disahkan dan pengguna akhir dalam sistem.

2.11 Memberi cara untuk memantau API anda untuk aktiviti luar biasa

Keselamatan API anda sekadar baik proses keselamatan anda dari hari ke hari.

Semestinya anda boleh memantau API untuk kelakuan luar biasa sama seperti anda memantau mana-mana tapak web dengan teliti. Jika sesuai, anda mungkin mencari perubahan dalam alamat IP atau pengguna menggunakan API pada waktu yang luar biasa dalam sehari. UK mempunyai panduan Pusat Keselamatan Siber Kebangsaan (NCSC) tentang cara untuk melaksanakan strategi pemantaun dan perkara khusus tentang cara memantau status keselamatan rangkaian dan sistem.

2.12 Apabila menamakan dan mengehos API anda

Semua penamaan API, dalam URL (termasuk nama API, ruang nama dan sumber anda) perlulah:

gunakan kata nama berbanding kata kerja

https://www.api.com/users bukan https://www.api.com/get-users

jadikannya ringkas, mudah dan boleh difahami dengan jelas. Url yang terlalu panjang atau sukar untuk difahami mungkin menunjukkan bahawa anda perlu menstrukturkan semula api anda atau memisahkan/ menggerakkan fungsi ke tempat lain.

https://www.api.com/users/123/discount bukan https://www.api.com/get-user-and-calculate-appropriate-discount/123

jadikannya boleh diteka, elakkan istilah teknikal atau pakar jika boleh

https://www.api.com/users/123/discount bukan https://www.api.com/get-most-recent-pricing-object-for-user/123

gunakan tanda sempang berbanding tanda garis bawah sebagai pemisah perkataan untuk nama berbilang perkataan

https://www.api.com/users/123/email-preferences bukan https://www.api.com/users/123/email_preferences

2.13 Apabila menggunakan sub-sumber

Sub-sumber mesti muncul di bawah sumber yang berkaitan dengannya, tetapi tidak boleh pergi lebih daripada tiga deep, sebagai contoh: https://www.api.com/resource/id/sub-resource/id/sub-sub-resource

Jika anda mencapai tahap ketiga kebutiran (sub-sub-sumber), anda perlu mengkaji semula pembinaan sumber anda untuk melihat jika ia sebenarnya suatu gabungan pelbagai sumber tahap pertama atau kedua.

2.14 Apabila menggunakan argumen pertanyaan

Anda perlu menggunakan parameter laluan untuk mengenal pasti sumber khusus atau sumber. Sebagai contoh: https://www.api.com/users/123

Anda hanya perlu membiarkan rentetan pertanyaan untuk digunakan dalam permintaan GET untuk menapis nilai yang dikembalikan daripada sumber individu, sebagai contoh: https://www.api.com/users?state=active https://www.api.com/users?page=2.

Anda tidak boleh menggunakan rentetan pertanyaan dalam permintaan GET untuk tujuan pengenalan, sebagai contoh: https://www.api.com/users?id=123

Rentetan pertanyaan tidak boleh digunakan untuk mentakrifkan kelakuan API anda, sebagai contoh: https://www.api.com/users?action=getUser&id=1

2.15 Apabila mengulangi API anda

Apabila mengulangi API anda untuk menambah fungsi baharu atau menambah baik, anda perlu meminimumkan gangguan untuk pengguna anda.

Bagi meminimumkan gangguan untuk pengguna, anda perlu:

membuat perubahan serasi ke belakang jika boleh – pengguna anda boleh mengabaikan sifat-sifat yang mereka tidak jangka atau fahami. Ini membolehkan anda untuk menambah medan bagi menyampaikan fungsi baharu tanpa memerlukan perubahan pada aplikasi pengguna.
buat titik akhir baharu tersedia untuk perubahan yang signifikan
berikan notis untuk titik akhir yang ditamatkan.

2.16 Apabila melakukan perubahan tidak serasi ke belakang

Apabila anda perlu membuat perubahan tidak serasi ke belakang, anda perlu mempertimbangkan:

menambah nombor versi dalam URL atau pengepala HTTP (bermula dengan /v1/ dan tambah dengan nombor bulat)
menyokong titik akhir lama dan baharu secara selari untuk tempoh masa yang sesuai sebelum memberhentikan yang lama
memberitahu pengguna API anda tentang cara untuk mengesahkan data, sebagai contoh, biar mereka tahu ketiadaan medan supaya mereka boleh memastikan peraturan pengesahan mereka akan melayan medan tersebut sebagai pilihan

Kadang kala, anda perlu membuat perubahan yang lebih besar dan memudahkan struktur objek kompleks dengan melipat data daripada pelbagai objek bersama. Dalam kes ini, jadikan objek baharu tersedia pada titik akhir baharu, sebagai contoh:

Gabungkan data tentang pengguna dan akaun daripada: https://www.api.com/users/123 https://www.api.com/accounts/123

Bagi menghasilkan: https://www.api.com/consolidated-account/123

2.17 Tetapkan dasar yang ditamatkan dengan jelas

Tetapkan dasar API yang ditamatkan dengan jelas supaya anda tidak menyokong aplikasi pelanggan lama untuk selama-lamanya.

Nyatakan tempoh untuk pengguna menaik taraf dan cara anda akan memaklumkan kepada mereka tentang tarikh akhir ini.

Strategi anda akan bergantung kepada beberapa faktor; jumlah pengguna API yang anda miliki, sama ada dalam organisasi anda atau pengguna luar, dan sejauh mana signifikan perubahan tersebut.

Sebagai contoh, jika API digunakan melalui penyepaduan tunggal dari jabatan lain dalam organisasi yang sama, ia mungkin dapat mendekati pembangun penyepaduan secara terus untuk memaklumkan kepada mereka tentang perubahan yang akan datang. Namun, jika API anda digunakan oleh 100 pengguna, anda perlu melaksanakan mekanisme untuk memberikan makluman kepada pengguna ini. Satu kaedah popular adalah dengan mengumumkan HTTP yang ditamatkan respons HTTP dengan menggunakan pengepala ‘Amaran’.

2.18 Berikan perkhidmatan ujian kepada pengguna

Pengguna API anda akan mahu menguji aplikasi mereka pada API anda sebelum ia dilakukan secara langsung. Jika anda hanya mempunyai API baca sahaja, anda tidak perlu menyediakan perkhidmatan ujian.

Sediakan perkhidmatan ujian kepada mereka (kadang kala dirujuk sebagai sandbox).

Jika API anda mempunyai kelakuan yang kompleks atau mengekalkan keadaan semasa, pertimbangkan untuk memberikan perkhidmatan ujian yang meniru perkhidmatan secara langsung tersebut sebanyak mungkin, tetapi jangan lupa kos untuk melakukan perkara ini.

Jika API anda memerlukan pengesahan, sebagai contoh, menggunakan OAuth 2.0, anda perlu merangkumkan perkara ini dalam perkhidmatan ujian anda atau menyediakan pelbagai tahap perkhidmatan ujian.

Bagi membantu anda memutuskan perkara untuk disediakan, lakukan penyelidikan pengguna – tanya pengguna API anda tentang perkhidmatan ujian yang mencukupi.

2.19 Uji pematuhan API anda

Anda perlu menyediakan pasukan pembangunan anda keupayaan untuk menguji API anda dengan menggunakan sampel data ujian , jika berkenaan. Pengujian API anda tidak boleh melibatkan penggunaan sistem pengeluaran dan data pengeluaran.