Maintenir la compatibilité descendante: à propos de la ligne de flottaison de l'iceberg

Avant de commencer à parler des principes de conception d'une API extensible, nous devons discuter du minimum d'hygiène. Un grand nombre de problèmes ne se seraient pas produits si les développeurs d'API étaient un peu plus responsables dans l'identification de leur domaine de responsabilité.

1. Fournissez le minimum de fonctionnalités

À tout moment, votre API est comme un iceberg: elle a une partie visible (documentée) et une partie invisible non documentée. Dans une bonne API, ces deux parties se rapportent à peu près comme la partie de surface et sous-marine d'un véritable iceberg, 1 sur 10. Pourquoi? Pour deux raisons évidentes.

• Les ordinateurs existent pour rendre les choses complexes faciles, et non l'inverse. Le code que les développeurs écriront au-dessus de votre API doit décrire la solution à un problème complexe en termes simples et concis. Si les développeurs sont obligés d'écrire plus de code dans votre API que vous n'en avez écrit vous-même, quelque chose s'est mal passé ici. Peut-être qu'une telle API n'est tout simplement pas nécessaire.

  
  
  
  
  

• La suppression des fonctionnalités de l'API est impossible sans de graves pertes. Si vous avez promis de fournir certaines fonctionnalités, vous devez maintenant les fournir "pour toujours" (jusqu'à la fin du support pour cette version majeure de l'API). Déclarer une fonctionnalité non prise en charge est un processus complexe, plein de conflits potentiels avec le consommateur.

  
  
  
  
  

La règle n ° 1 est la plus simple: si vous n'avez pas à exposer certaines fonctionnalités, vous n'avez pas besoin de les exposer. Elle peut être formulée comme suit: chaque entité, chaque champ, chaque méthode de l'API publique est une solution produit . Il doit y avoir de bonnes raisons pour lesquelles une entité est documentée.

2. Évitez les zones grises et la sous-estimation

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

---

Ceci est un brouillon pour un prochain chapitre du livre sur le développement d'API. Le travail se fait sur Github . La version anglaise du même chapitre est publiée sur support . J'apprécierais que vous puissiez le partager sur reddit - je ne peux pas moi-même selon la politique de la plate-forme.