Mempertahankan Kompatibilitas Mundur: Tentang Garis Air Gunung Es

Sebelum kita mulai berbicara tentang prinsip desain API yang dapat diperluas, ada minimum higienis yang harus dipertimbangkan. Sejumlah besar masalah tidak akan terjadi jika pengembang API sedikit lebih bertanggung jawab dalam mengidentifikasi area tanggung jawab mereka.

1. Sediakan jumlah fungsionalitas minimum

Pada waktu tertentu, API Anda seperti gunung es: ia memiliki bagian yang terlihat (terdokumentasi) dan bagian yang tidak terdokumentasi. Dalam API yang baik, kedua bagian ini berhubungan satu sama lain secara kasar seperti permukaan dan bagian bawah air dari gunung es yang sebenarnya, 1 dari 10. Mengapa ini? Untuk dua alasan yang jelas.

• Komputer ada untuk mempermudah hal-hal yang kompleks, bukan sebaliknya. Kode yang akan ditulis pengembang di atas API Anda harus menjelaskan solusi untuk masalah kompleks dalam istilah yang sederhana dan ringkas. Jika pengembang dipaksa untuk menulis lebih banyak kode di API Anda daripada yang Anda tulis sendiri, ada yang salah di sini. Mungkin API semacam itu tidak diperlukan.

  
  
  
  
  

• Menghapus fungsionalitas dari API tidak mungkin dilakukan tanpa kerugian serius. Jika Anda telah berjanji untuk menyediakan beberapa fungsi, Anda sekarang harus menyediakannya "selamanya" (hingga akhir masa dukungan untuk versi utama API ini). Menyatakan fungsionalitas yang tidak didukung adalah proses yang kompleks, penuh dengan potensi konflik dengan konsumen.

  
  
  
  
  

Aturan # 1 adalah yang paling sederhana: jika Anda tidak perlu mengekspos beberapa fungsionalitas, maka Anda tidak perlu mengeksposnya. Ini dapat dirumuskan sebagai berikut: setiap entitas, setiap bidang, setiap metode di API publik adalah solusi produk . Harus ada alasan bagus mengapa entitas didokumentasikan.

2. Hindari area abu-abu dan pernyataan yang meremehkan

, . , . , , , «» - , — API, , . «» . .

API , :

• ;

  
  
  
  
  

• — , , ..;

  
  
  
  
  

. , , .

3.

. , : - , , ?

1. SDK .

//  
let order = api.createOrder();
//   
let status = api.getStatus(order.id);

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

, - . , id 404



, , . , strong eventual.

? , . , — . , — .

: «, !» — , , . , , createOrder



, SDK - :

let order = api.createOrder();
let status;
while (true) {
    try {
        status = api.getStatus(order.id);
    } catch (e) {
        if (e.httpStatusCode != 404 || timeoutExceeded()) {
            break;
        }
    }
}
if (status) {
    …
}

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

, , , . API, createOrder



SDK , getStatus



.

— API. , , .

2. :

let resolve;
let promise = new Promise(
    function (innerResolve) {
        resolve = innerResolve;
    }
);
resolve();

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

, callback-, new Promise



, resolve



resolve()



. : new Promise



callback-.

, , . API — . , ; , , API. .

3. , API , :

//    
//     
//   
object.animateWidth('100px', '500px', '1s');
//     
object.observe('widthchange', observerFunction);

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

: observerFunction



? , SDK 10 — observerFunction 10 '140px', '180px' .. '500px'. API — , observerFunction



.

- — , , , , SDK 10 . , , observerFunction



'500px' - — - .

— callback — .

4. , , :

GET /v1/orders/{id}/events/history
→
{
    "event_history": [
        {
            "iso_datetime": "2020-12-29T00:35:00+03:00",
            "new_status": "created"
        },
        {
            "iso_datetime": "2020-12-29T00:35:10+03:00",
            "new_status": "payment_approved"
        },
        {
            "iso_datetime": "2020-12-29T00:35:20+03:00",
            "new_status": "preparing_started"
        },
        {
            "iso_datetime": "2020-12-29T00:35:30+03:00",
            "new_status": "ready"
        }
    ]
}

      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

, - « », . .. "preparing_started", "ready", "payment_approved". , - — , . , , .

, (, - ) - , - — , . , - , . . - ; , .

-, ; -, "payment_approved" "preparing_started" ( — , , ) .

.

4.

, , — . - , .

, , - . - , «». , , . - , .. -, , , - , .

« -» — , , - , . . «» — API; — « », III.

---

Ini adalah draf untuk bab selanjutnya dari buku tentang pengembangan API. Pekerjaan dilakukan di Github . Versi bahasa Inggris dari bab yang sama diterbitkan pada medium . Saya akan sangat menghargai jika Anda dapat membagikannya di reddit - Saya sendiri tidak dapat sesuai dengan kebijakan platform.