NB : This is a draft of two new chapters of my book on API Design. The text contains references to the previous chapters.
Strong connectivity and related issues
In the previous sections, we tried to give theoretical rules and principles, and illustrate them with practical examples. However, understanding the principles of designing API resilient to change requires more practice than anything else. The knowledge of where to "lay the straw" is in many ways "the son of difficult mistakes." You cannot foresee everything - but you can develop the necessary level of technical intuition.
Therefore, in this section, we will proceed as follows: take our model API from the previous section, and check it for stability at every possible point - let's do some "analysis of variance" of our interfaces. Even more specifically, we will approach each entity with the question "what if?" - what if we need to provide partners with the ability to write their own independent implementation of this piece of logic.
The first important point to pay attention to: we are talking specifically about the implementation options for product logic . Not about the options for the implementation of the entity : changes in the API are made primarily in order to make it possible to do something that was not provided for by the original design - something useful. Your customers won't be reimplementing interfaces just like that.
This consideration introduces certain restrictions that allow us not to blindly vary the interfaces (after all, there are an infinite number of such options, and to provide for all of them is Sisyphean work): we need to understand, first of all, why certain changes are needed, and from here we are already we will understand how they should be introduced.
The second important point is that many of the solutions that allow for this variation are already built into the design of the API. We covered some of them (for example, the issue of determining readiness) in more detail in the previous chapters, and some gave without comment - it's time to explain why these decisions were made.
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 . .
- (.. API), : , .
- : .
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); ) }
This is a draft of two new chapters in the upcoming Backward Compatibility section of my book on API development. The work is done on Github . The English version of the same chapter is published on medium . I would be grateful if you could share it on reddit - I myself cannot according to the platform's policy.