Clever Geek Handbook

Schwache KonnektivitÀt

NB : Dies ist ein Entwurf von zwei neuen Kapiteln meines Buches ĂŒber API-Design. Der Text enthĂ€lt Verweise auf die vorherigen Kapitel.







Starke KonnektivitÀt und damit verbundene Probleme



In den vorherigen Abschnitten haben wir versucht, theoretische Regeln und Prinzipien anzugeben und diese anhand praktischer Beispiele zu veranschaulichen. Das VerstĂ€ndnis der Prinzipien fĂŒr das Entwerfen einer API, die gegenĂŒber Änderungen widerstandsfĂ€hig ist, erfordert jedoch mehr Übung als alles andere. Das Wissen, wo man "den Strohhalm legt", ist in vielerlei Hinsicht "der Sohn schwieriger Fehler". Sie können nicht alles vorhersehen - aber Sie können das notwendige Maß an technischer Intuition entwickeln.







Daher werden wir in diesem Abschnitt wie folgt vorgehen: Nehmen Sie unsere Modell-API aus dem vorherigen Abschnitt und ĂŒberprĂŒfen Sie sie an jedem möglichen Punkt auf StabilitĂ€t. Wir werden eine "Variationsanalyse" unserer Schnittstellen durchfĂŒhren. Insbesondere werden wir uns jeder EntitĂ€t mit der Frage "Was wĂ€re wenn?" Ansprechen. - Was ist, wenn wir den Partnern die Möglichkeit geben mĂŒssen, ihre eigene unabhĂ€ngige Implementierung dieser Logik zu schreiben?







Der erste wichtige Punkt, auf den Sie achten sollten: Wir sprechen speziell ĂŒber die Optionen fĂŒr die Implementierung der Produktlogik . Nicht zu den Optionen fĂŒr die Implementierung der EntitĂ€t : Änderungen in der API werden hauptsĂ€chlich vorgenommen, um es zu ermöglichen, etwas zu tun, das im ursprĂŒnglichen Design nicht vorgesehen war - etwas NĂŒtzliches. Ihre Kunden werden Schnittstellen nicht einfach so neu implementieren.







Diese Überlegung fĂŒhrt bestimmte EinschrĂ€nkungen ein, die es uns ermöglichen, die Schnittstellen nicht blind zu variieren (schließlich gibt es unendlich viele solcher Optionen, und fĂŒr alle ist Sisyphean-Arbeit vorzusehen): Wir mĂŒssen zunĂ€chst verstehen, warum bestimmte Änderungen sind erforderlich, und von hier aus werden wir bereits verstehen, wie sie eingefĂŒhrt werden sollten.







Der zweite wichtige Punkt ist, dass viele der Lösungen, die diese Variation ermöglichen, bereits in das Design der API integriert sind. Wir haben einige von ihnen (zum Beispiel das Problem der Bestimmung der Bereitschaft) in den vorherigen Kapiteln ausfĂŒhrlicher behandelt, und einige haben kommentarlos angegeben - es ist Zeit zu erklĂ€ren, warum diese Entscheidungen getroffen wurden.







NB: , ; ad hoc , . API ; , , .







, . ?







  • , «» ;
  • , .


. , ? , «»: , . , :







//   
POST /v1/recipes
{
  "id",
  "product_properties": {
    "name",
    "description",
    "default_value"
    //  , 
    //   
    

  },
  "execution_properties": {
    //  
    "program_id",
    //   
    "parameters"
  }
}


, , . , — .







, 11: . :







"product_properties": {
  // "l10n" —  
  //  "localization"
  "l10n" : [{
    "language_code": "en", 
    "country_code": "US", 
    "name", 
    "description" 
  }, /*     */ 
 ]
]


— default_volume



? , , , . , , , «300 », «10 ». :







  • , ;
  • , .


, API - — , API. , — . .







, , API . — name



description



? , . — /v1/search



, : search



?







— , UI . -, name



description



— , ( ) ( ). , API . , UI ? , , : name



— «-» , . -, , UI; -, . , , «», «» «» « » « ».







— UI ( ) , ( , , ). product_properties



, , .







, — . , , , () ( , ). API « », . , : . .









: , . — , (, , .. API) .







, . - , API, — , API . - API :







l10n.volume.format(value, language_code, country_code)
// l10n.formatVolume('300ml', 'en', 'UK') → '300 ml'
// l10n.formatVolume('300ml', 'en', 'US') → '10 fl oz'


API , , , . , , :







//    
//   
PUT /formatters/volume/ru
{
  "template": "{volume} "
}
//    
//      «»
PUT /formatters/volume/ru/US
{
  //     
  // ,   
  "value_preparation": {
    "action": "divide",
    "divisor": 30
  },
  "template": "{volume} ."
}


NB: , , , , , (, , ), (.. ). .







name



description



. , , (, , API) «». name



description



, UI. UI .







GET /v1/layouts/{layout_id}
{
  "id",
  //      ,
  //     
  // 
  "kind": "recipe_search",
  //    ,
  //     
  //   
  "properties": [{
    //    ,  `name`
    //      
    //     —
    //      `seach_title`
    "field": "search_title",
    "view": {
      //   ,
      //    
      "min_length": "5em",
      "max_length": "20em",
      "overflow": "ellipsis"
    }
  }, 
],
  //   
  "required": ["search_title", "search_description"]
}


, , . :







PUT /v1/recipes/{id}/properties/l10n/{lang}
{
  "search_title", "search_description"
}


:







POST /v1/layouts
{
  "properties"
}
→
{ "id", "properties" }


, UI , , .







— , — execution_properties



, , . :







POST /v1/recipes
{ "id" }
→
{ "id" }


, «» , . , , -, :







POST /v1/recipe-builder
{
  "id",
  //   
  "product_properties": {
    "default_volume",
    "l10n"
  },
  //  
  "execution_properties"
  //   
  "layouts": [{
    "id", "kind", "properties"
  }],
  //   
  "formatters": {
    "volume": [
      { "language_code", "template" },
      { "language_code", "country_code", "template" }
    ]
  },
  //  ,  
  //    
  //    
  

}


, — . , — , , - . , , , , : ( ), , 11.







POST /v1/recipes/custom
{
  //   :
  // ,    
  "namespace": "my-coffee-company",
  //   
  "id_component": "lungo-customato"
}
→
{
  "id": "my-coffee-company:lungo-customato"
}


, : , . , "common", . (, , , API .)









, . , API 9 «» « ». , program-matcher



:







GET /v1/recipes/{id}/run-data/{api_type}
→
{ /*   
       
        
       API */ }


:







  • API -;
  • API ;
  • API .


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







program_run_id



, . .







, , . API - API. , , -, API. API , - ?







, API : , () . API — , :







//   
// - 
PUT /partners/{id}/coffee-machines
{
  "coffee-machines": [{
    "id",
    

    "program_api": {
      "program_run_endpoint": {
        /* - 
              */
        "type": "rpc",
        "endpoint": <URL>,
        "format"
      },
      "program_state_endpoint",
      "program_stop_endpoint"
    }
  }, 
]
}


NB: API ( program_run_endpoint



, program_state_endpoint



, .)







API , , API . .







  1. (.. API), : , .
  2. : .


2 , 1. , , — , , . , , program_modify_endpoint



, ( , ). , , ( , ) .







- , . : , API , . , , , modify



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







, , program_takeout_endpoint



. :







  • program_takeout_endpoint



    , program_modify_endpoint



    ;
  • program_modify_endpoint



    , program_takeout_endpoint



    .


, . , takeout



. - modify



, . , , — API , .







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







, . API « », .







? : , . ? - :







  • API , ; , : - - , , - ;
  • API , API ; , .


, , , : , . , « ».







:







  • , ;
  • : , .


, , (- ) . SDK :







/*   
       - */
registerProgramRunHandler(apiType, (program) => {
  //   
  //    
  let execution = initExecution(
);
  //   
  //  
  program.context.on('takeout_requested', () => {
    //    ,
    //  
    execution.prepareTakeout(() => {
        //      ,
        //   
        execution.context.emit('takeout_ready');
    });
  });

  return execution.context;
});


NB: HTTP API , GET /program-run/events



GET /partner/{id}/execution/events



, . , Apache Kafka Amazon SQS.







, , , , :







  • takeout



    takeout_requested



    /takeout_ready



    ;
  • , API , context



    , ;
  • , .


. API , . API : . ? , ; - ( !) , ( ).







, . , :







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


, — , - .







, , (, ) API, , . program



( , , ); execution



( , , API). , execution



- , - API, program



- , .







, . API, , , , . , UI. , SDK.









, , . , — . :







/*   
       - */
registerProgramRunHandler(apiType, (program) => {
  //   
  //    
  let execution = initExection(
);
  //   
  //  
  program.context.on('takeout_requested', () => {
    //    ,
    //  
    execution.prepareTakeout(() => {
      /*      ,
            ,  
             */
      // execution.context.emit('takeout_ready')
      program.context.set('takeout_ready');
      //    :
      // program.setTakeoutReady();
    });
  });
  //       
  //   - 
  // return execution.context;
}


, . : , . , , , , . .







, , , :







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


, API API , «» «-».







NB: . , — Redux. Redux :







execution.prepareTakeout(() => {
  //     
  //     ,
  //    
  //      
  dispatch(takeoutReady());
});


, , — , API, . ( -) , , : , , .







execution.prepareTakeout(() => {
  //     
  //     ,
  //    
  // 
  program.context.dispatch(takeoutReady());
});
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    


//  program.context.dispatch
ProgramContext.dispatch = (action) => {
  // program.context   
  //  ,   
  // ,    
  globalContext.dispatch(
    //     
    //     
    //    
    // 
    this.generateAction(action);
  )
}




Dies ist ein Entwurf von zwei neuen Kapiteln im nĂ€chsten Abschnitt zur AbwĂ€rtskompatibilitĂ€t meines Buches ĂŒber die API-Entwicklung. Die Arbeit wird an Github erledigt . Die englische Version desselben Kapitels wird auf Medium veröffentlicht . Ich wĂ€re Ihnen dankbar, wenn Sie es auf reddit teilen könnten - ich selbst kann es nicht gemĂ€ĂŸ den Richtlinien der Plattform tun.







More articles:


All Articles