Mantendo a compatibilidade com versões anteriores: sobre a linha de corte do iceberg

Antes de começarmos a falar sobre os princípios de design de uma API extensível, devemos discutir o mínimo de higiene. Um grande número de problemas não teria acontecido se os desenvolvedores de API fossem um pouco mais responsáveis ​​na identificação de sua área de responsabilidade.

1. Fornece a quantidade mínima de funcionalidade

A qualquer momento, sua API é como um iceberg: ela tem uma parte visível (documentada) e uma parte não documentada invisível. Em uma boa API, essas duas partes se relacionam aproximadamente como a superfície e a parte subaquática de um iceberg real, 1 em 10. Por que isso? Por duas razões óbvias.

• Os computadores existem para facilitar as coisas complexas, não vice-versa. O código que os desenvolvedores escreverão sobre sua API deve descrever a solução para um problema complexo em termos simples e concisos. Se os desenvolvedores forem forçados a escrever mais código em sua API do que você mesmo escreveu, algo deu errado aqui. Talvez essa API simplesmente não seja necessária.

  
  
  
  
  

• Remover funcionalidade da API é impossível sem perdas graves. Se você prometeu fornecer alguma funcionalidade, agora você deve fornecê-la "para sempre" (até o final do suporte para esta versão principal da API). Declarar funcionalidade sem suporte é um processo complexo, repleto de conflitos potenciais com o consumidor.

  
  
  
  
  

A regra nº 1 é a mais simples: se você não precisa expor alguma funcionalidade, não precisa expor. Ele pode ser formulado da seguinte forma: cada entidade, cada campo, cada método na API pública é uma solução de produto . Deve haver bons motivos para uma entidade ser documentada.

2. Evite áreas cinzentas e eufemismo

, . , . , , , «» - , — 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.

---

Este é um rascunho para um capítulo futuro do livro sobre desenvolvimento de API. O trabalho é feito no Github . A versão em inglês do mesmo capítulo é publicada na mídia . Eu agradeceria se você pudesse compartilhar no reddit - eu mesmo não posso de acordo com a política da plataforma.