Get best of the week

Panduan Gaya API, atau jangan buat pengguna berpikir



Halo! Nama saya Lesha Rutskoi dan saya seorang manajer produk di Wrike. Sebelum itu, ia bekerja di Adform dan PandaDoc. Selama lima tahun terakhir, saya telah melakukan segala hal yang berkaitan dengan integrasi dan API.

Wrike adalah kolaborasi SaaS dan produk manajemen proyek. Kami ingin pengembang membangun solusi mereka berdasarkan Wrike, dan untuk ini kami membutuhkan API kami agar nyaman. Pada saat yang sama, kami memiliki 9 kantor di seluruh dunia, dan 3 di antaranya adalah kantor pengembangan. Sangat sulit untuk membuat API yang konsisten menggunakan tim terdistribusi yang berbicara bahasa yang berbeda. Ada kemungkinan yang berkembang bahwa keputusan mereka akan mulai saling bertentangan. Dalam hal ini, seseorang tidak dapat melakukannya tanpa seperangkat aturan yang seragam untuk semua.

Jika Anda juga bekerja dengan cara terdistribusi dan membuat API Anda sendiri, maka API Panduan Gaya dapat membantu Anda. Saya ingin memberi tahu Anda masalah umum apa yang dipecahkan dan bagaimana hal itu membuat hidup lebih mudah bagi pengembang. Saya juga akan membagikan pengalaman saya dalam menulis dan mengimplementasikan Panduan Gaya API saya sendiri di perusahaan.

Mengapa kita membutuhkan API yang nyaman?


Banyak pembaca mungkin harus menyelesaikan masalah menggunakan API yang tidak terlalu nyaman. Ya, ini tidak terlalu sederhana dan membutuhkan waktu lebih lama, tetapi biasanya Anda masih bisa menyelesaikan masalah.

Lalu mengapa membuang waktu dan upaya tim untuk membuat API lebih baik? Jawabannya cukup sederhana: sangat sering keputusan tentang penggunaan produk Anda dibuat oleh pengembang, terutama ketika menyangkut API dan integrasi. Oleh karena itu, penting untuk berpikir tidak hanya tentang pengalaman pengguna (UX), tetapi juga tentang pengalaman DX-developer.

Saya akan memberi contoh. Saya pernah bekerja di tim yang bertanggung jawab atas semua integrasi produk. Seringkali di pertengahan kuartal, ketika rencana kami sudah diuraikan, seorang pemasar datang dan berkata: “Z telah membuat pasar baru dan akan merilis versi platform berikutnya. Segera mereka akan memiliki acara publik yang keren di mana kita dapat berbicara tentang integrasi dan kesuksesan kita! Akan sangat bagus jika kita segera menulis integrasi ini sekarang. ” Apa yang kami lakukan dalam kasus ini? Jika pengembang berpengalaman dalam tim dapat membuat prototipe kerja minimum dalam tiga hari, maka paling sering dalam dua atau tiga minggu kami berhasil membawa tugas ke kondisi sempurna. Jika beberapa hari hilang, maka API dan dokumentasinya biasa saja.Tidak ada gunanya bagi kami untuk merancang ulang rencana dan melakukan integrasi baru - semua sama, tidak ada yang berharga akan berhasil pada tanggal jatuh tempo. Ingat bahwa produk Anda mungkin berada dalam situasi seperti itu - mitra akan memutuskan apakah akan berurusan dengan Anda tergantung pada seberapa cepat dan nyaman Anda dapat mulai bekerja dengan API Anda.

Tetapi hampir tidak ada orang yang ingin merancang API yang buruk. Mengapa semua orang berbeda? Biasanya API berkembang seperti ini. Ketika startup mulai tumbuh dan klien pertama datang ke sana, salah satu tim membuat titik akhir dan memutuskan untuk mentransfer versi ke URL:

gambar

Secara bertahap klien baru dan kebutuhan baru muncul. Orang-orang dari tim kedua termasuk dalam pekerjaan, yang percaya bahwa lebih baik menggunakan tipe Media mereka sendiri untuk versi:

gambar

Setelah beberapa saat, tim ketiga tiba. Di sebuah konferensi, mereka mengetahui bahwa Stripe meng-versi-kan API-nya dengan tanggal rilis utama. Dan mereka memutuskan untuk melakukan hal yang sama:

gambar

Hasilnya adalah API di mana ada tiga metode pembuatan versi. Semua metode bekerja, tetapi bekerja secara berbeda.

Sebagai pengembang, tidak nyaman bagi saya untuk menggunakan API semacam itu. Dan alasannya bukan karena saya lebih suka satu pendekatan untuk versi ke semua orang. Hanya menggunakan beberapa metode sekaligus tidak nyaman. Anda harus menulis kode tiga kali yang berfungsi dengan API, atau menggunakan tiga pustaka yang berbeda. Dan ini berarti akan ada kesalahan tiga kali lebih banyak.

Dan ada tanggal dan waktu. Bahkan dengan menggunakan pendekatan standar, data dapat ditransmisikan dengan cara yang berbeda: oleh zona waktu server Anda, dengan GMT, pada waktu di klien, dalam waktu Unix. Klien harus membawa semua data ke satu format.

Pesan kesalahan umumnya melakukan segalanya secara berbeda. Misalnya, seperti ini:

gambar

Atau seperti ini:

gambar

Ada juga pesan kesalahan favorit saya - jawaban kosong:

gambar

Yah, hanya klasik - jawabannya adalah 200 OK, di dalamnya terletak JSON dengan deskripsi tentang apa yang salah.

Menurut pendapat saya, hal terpenting dalam API yang baik adalah konsistensi . Tidak masalah pendekatan apa pun untuk versi yang Anda pilih, yang utama adalah bahwa itu sama di seluruh API. Solusi yang bahkan lebih sukses adalah dengan mengambil pendekatan populer yang sudah diambil oleh perusahaan lain. Kemungkinan besar, klien Anda sudah menemukannya, dan mereka memiliki kode yang sudah jadi atau perpustakaan. Tidak perlu berpikir lagi, Anda bisa menggunakan alat yang sudah jadi.

Pendekatan tunggal untuk membuat API sangat penting bagi perusahaan besar dengan tim yang didistribusikan. Jika sepuluh orang di ruangan membuat startup, maka setiap pengembang dapat dengan mudah mengetuk tetangga dan menyetujui atau melihat masalah utama selama tinjauan kode. Di perusahaan besar, semakin sulit.

API Panduan Gaya akan membantu Anda memecahkan masalah seperti itu. Ini adalah dokumen yang menjelaskan prinsip-prinsip desain API Anda. Jika semua orang menggunakan pendekatan yang sama, tampaknya API dikembangkan oleh satu orang, dan tidak banyak tim yang berbeda. Pendekatan ini sangat mirip dengan Panduan Gaya Kode ketika tim sepakat tentang bagaimana mereka menulis kode. Seseorang dari satu tim dapat melihat basis kode dari tim lain dan dengan cepat memahami apa yang terjadi di sana.

Bagaimana cara membuat Panduan Gaya API Anda sendiri?


Arnauld Lauret (dikenal sebagai Handyman API ) menciptakan situs keren - Stylebook API . Dia menyusun Panduan Gaya yang dapat diakses publik, yang dimasukkan oleh berbagai perusahaan (Cisco, Google, Red Hat, lembaga pemerintah, dan banyak lainnya) ke dalam domain publik.

Pedoman dibagi menjadi beberapa topik di situs. Misalnya, jika Anda tertarik untuk versi, maka pada tab Versioning Anda dapat mengetahui bagaimana berbagai perusahaan menyelesaikan masalah ini.

Belajarlah dari pengalaman orang lain! Tapi sepenuhnya menyalin Panduan Gaya orang lain bukanlah ide yang baik. Tetap saja, dia memecahkan masalah perusahaan lain, bukan milikmu.

Dalam Panduan Gaya Anda, Anda harus menambahkan topik yang dekat dengan perusahaan Anda dan menyelesaikan masalah Anda. Mungkin Anda memiliki banyak aplikasi seluler, dan ukuran jawabannya penting bagi Anda. Kemudian jelaskan prinsip-prinsip yang terkait dengan aspek ini. Atau Anda setuju dengan tim internal bahwa sudah waktunya untuk melihat monolith menjadi layanan microser yang akan berkomunikasi satu sama lain melalui Message Broker. Dalam hal ini, Anda harus memasukkan prinsip-prinsip yang menurutnya Anda akan menggunakan Kafka atau alat lain dalam Panduan Gaya API.

Apa lagi yang termasuk dalam API Panduan Gaya


Juga, Panduan Gaya harus mencakup nilai-nilai dasar dan pendekatan teknik yang dipatuhi oleh perusahaan.

Apa yang bisa mereka

  • Write APIs in English. , . - , , . Style Guide, , .
  • API First principle. API : , , frontend-. , API . , , .
  • Gunakan REST dan JSON. Ini bisa penting jika Anda ingin audiens seluas mungkin menggunakan API atau platform Anda. Terlepas dari kenyataan bahwa GraphQL telah menjadi semakin populer sejak 2017, tidak semua orang mengetahuinya. Sebagian besar pengembang, kemungkinan besar, tidak pernah menggunakannya, yang berarti mereka akan menambah waktu untuk perendaman dan pengembangan. Mengapa membuat kompleksitas?

Selanjutnya, prinsip-prinsip dasar dapat dituangkan pada topik. Misalnya, di dalam prinsip menggunakan REST dan JSON, Anda dapat dengan mudah menentukan topik mana yang harus dijelaskan dalam Panduan:

  • Pilih API REST dengan payload JSON
    • Permintaan HTTP
    • Kode status HTTP
    • Json

Lebih jauh tentang setiap topik, Anda dapat membuat aturan yang harus diikuti oleh semua tim di perusahaan:

  • Permintaan HTTP
    • HARUS menggunakan metode HTTP dengan benar
    • Header HTTP khusus HARUS mengikuti konvensi penamaan

Saya sangat suka pendekatan yang menggambarkan perlunya mengikuti aturan melalui kata kerja HARUS, HARUS, atau MUNGKIN (dipinjam dari RFC 2119 ). Kemudian semua orang yang membaca Panduan Gaya akan membedakan antara peraturan dan rekomendasi wajib.

Begini caranya, misalnya, tampilannya di Zalando :

gambar

Hal-hal yang perlu diingat ketika memulai Panduan Gaya


  • . , . , , . , , . API management , . API.
  • . - 15- . rate limiting, .. — , , - .
  • . , OAuth, REST. , , , scopes .
  • . , , .
  • . , . , . . . , .
  • . , , .
  • . , , .. : , «user», , «user», .
  • . , — . , (OpenAPI-, -) . .

API Style Guide?


Anda telah membuat Panduan Gaya API Anda, dan sekarang tetap menerapkannya. Ini juga tidak mudah. Saya akan membagikan pengalaman saya menerapkan Panduan Gaya API di salah satu tempat saya bekerja. Perusahaan memiliki struktur yang kompleks: ratusan insinyur, lusinan tim yang didistribusikan di empat kantor pengembangan, kolega berbicara dalam berbagai bahasa.

Pertama, Anda perlu meyakinkan para pemangku kepentingan. Dan di sini kita sering berbicara tentang para pemimpin teknis di berbagai bidang dan perwakilan bisnis. Setiap orang harus memahami masalah apa yang ingin kita selesaikan dan bagaimana Style Guide dapat membantu. Dalam contoh saya, semua pemangku kepentingan memahami bahwa API yang baik adalah keuntungan penting. Banyak klien datang dengan permintaan seperti itu, dan para pesaing tidak tertidur dan secara aktif memperluas cakupan peluang yang tersedia melalui API mereka.

Langkah selanjutnya adalah menemukan tim yang akan melakukan ini. Dalam kasus saya, perusahaan sudah memiliki tim terpisah yang mendukung API eksternal. Dia paling mengerti perlunya perubahan, karena dia selalu dihadapkan dengan kesulitan dalam pekerjaannya. Anggota tim ini senang untuk berpartisipasi dalam proyek ini.

Bagaimana tim menerapkan API Panduan Gaya?

  • Dia berbicara tentang inisiatif di konferensi internal dan hackathon sehingga semua orang di perusahaan akan mengerti apa yang sedang dibahas. Ini membantu menarik orang-orang yang berpikiran sama yang sangat berguna di tahap selanjutnya.
  • Mempersiapkan draft Style Guide, yang kemudian setuju dengan juara API (tentang mereka sedikit lebih jauh).
  • Mempresentasikan proyek kepada tim. Orang-orang pergi ke setiap kantor pengembangan dan berbicara dengan hampir semua tim, menjelaskan makna proyek dan melakukan pelatihan.
  • Membantu dengan desain API. Sulit bagi banyak tim untuk melakukan segala sesuatu pada panduan pertama kali. Bantuan dan penjelasan tambahan berguna di sini, terutama dalam situasi yang tidak biasa.
  • Melakukan review. Penting untuk memverifikasi bahwa semua tim bertindak sesuai dengan Panduan Gaya.

Sangat sulit bagi satu tim di perusahaan besar untuk menerapkan perubahan signifikan tersebut. Butuh bantuan. Di sini juara API terhubung - arsitek dan techlide dari setiap arah yang membantu untuk mengintegrasikan ide ke dalam tim dan divisi mereka.

Ketika perubahan kunci terjadi, ketidakpuasan sering muncul. Dalam hal ini, Anda membutuhkan otoritas yang dapat meyakinkan orang-orang ini tentang perlunya perubahan. Anak-anak adalah orang yang paling cocok untuk ini.

Juara API di saluran Slack yang terpisah membahas masalah dan saran yang muncul. Perubahan kecil diperkenalkan segera, sementara yang lebih besar membutuhkan diskusi rinci. Dalam hal ini, pemrakarsa menulis proposal resmi: masalah apa yang perlu dipecahkan, metode solusi apa yang sudah ada, apa kelebihan dan kekurangan yang mereka miliki. Kemudian selama 1-2 hari kami berkumpul di luar kantor di luar kantor, mendiskusikan ide-ide, memilih solusi dan memperbaikinya. Kemudian kami memberi tahu tim kami tentang keputusan yang kami buat: mengapa kami membuatnya dan apa yang perlu dilakukan selanjutnya.

Juga, juara API membantu melakukan tinjauan di bidang mereka. Orang-orang di tim mereka pertama-tama berpaling kepada mereka, dan kemudian tinjauan terakhir dilakukan oleh tim yang menciptakan Panduan Gaya.

Setelah beberapa waktu, komunitas API mulai terbentuk di perusahaan. Itu termasuk orang-orang yang telah melalui beberapa siklus peninjauan, menemukan apa desain yang baik dan benar, mengapa itu diperlukan dan bagaimana membuatnya. Kami membuat obrolan besar di mana semua orang bisa mengajukan pertanyaan, dan anggota komunitas API membantu menyelesaikannya.

Anda tidak dapat menerapkan pendekatan hanya di tingkat teknik. Tim penjualan, dukungan, dan pemasaran juga harus memahami skenario pengguna apa yang dicakup oleh API, nilai apa yang dibawanya, bagaimana kaitannya dengan strategi perusahaan dan bagaimana cara menyampaikan informasi tentang hal itu kepada pelanggan dengan benar.

Kami mencoba memperkenalkan semua ini ke dalam orientasi sebagian besar tim di perusahaan, termasuk yang non-teknik. Ini juga diperlukan agar semua orang mengerti kapan, dalam kasus apa dan kepada siapa Anda dapat meminta bantuan.

Otomatisasi


Topik penting terakhir adalah otomatisasi proses rutin. Ulasan dapat menjadi contoh utama. Di perusahaan besar dengan sejumlah besar tim, kemungkinan besar, Anda perlu melakukan banyak ulasan. Saya tidak ingin membuang waktu untuk masalah dasar seperti deskripsi kesalahan yang hilang atau format ID yang salah.

Beberapa alat dapat membantu dengan ini:

  • Zally dari Zalando memeriksa untuk melihat apakah spesifikasi OpenAPI cocok dengan Panduan Gaya API Anda. Konfigurasi dasar Zally memeriksa kepatuhan terhadap Panduan Gaya Zalando, tetapi Anda dapat mendefinisikan ulang dan menambahkan aturan Anda sendiri.
  • Apiary's Dredd memeriksa untuk melihat apakah implementasi REST API final cocok dengan desain Anda, yaitu OpenAPI, Blueprint, atau spesifikasi RAML.

Artikel ini adalah transkrip pembicaraan saya dengan Konferensi Platform Developers Miro . Anda dapat menemukan video pidato di sini .

Dengan senang hati saya akan menjawab pertanyaan Anda tentang penerapan Panduan Gaya API. Ini juga akan keren jika Anda berbagi pengalaman serupa!

Terima kasih khusus kepada Daria Ivanova atas bantuannya dalam mempersiapkan artikel ini!

More articles:


All Articles