diff --git a/src/ru/clean-copy/04-Раздел III. Обратная совместимость/03.md b/src/ru/clean-copy/04-Раздел III. Обратная совместимость/03.md index 54b6a42..9fe6955 100644 --- a/src/ru/clean-copy/04-Раздел III. Обратная совместимость/03.md +++ b/src/ru/clean-copy/04-Раздел III. Обратная совместимость/03.md @@ -83,7 +83,7 @@ PUT /v1/partners/{partnerId}/coffee-machines Часто вместо добавления нового метода можно добавить просто необязательный параметр к существующему интерфейсу — в нашем случае, можно добавить необязательный параметр `options` к вызову `PUT /cofee-machines`. -**NB**. Когда мы говорим о фиксации договоренностей, действующих в настоящий момент — речь идёт о *внутренних* договорённостях. Мы должны были потребовать от партнёров поддерживать указанный список опций, когда обговаривали формат взаимодействия. Если же мы этого не сделали изначально, а потом решили зафиксировать договорённости в ходе расширения функциональности внешнего API — это очень серьёзная заявка на нарушение обратной совместимости, и так делать ни в коем случае не надо, см. главу [«О ватерлинии айсберга»](#back-compat-iceberg-waterline). +**NB**. Когда мы говорим о фиксации договоренностей, действующих в настоящий момент — речь идёт о *внутренних* договорённостях. Мы должны были потребовать от партнёров поддерживать указанный список опций, когда обговаривали формат взаимодействия. Если же мы этого не сделали изначально, а потом решили зафиксировать договорённости в ходе расширения функциональности внешнего API — это очень серьёзная заявка на нарушение обратной совместимости, и так делать ни в коем случае не надо, см. главу [«О ватерлинии айсберга»](#back-compat-iceberg-waterline). #### Границы применимости diff --git a/src/ru/clean-copy/07-Раздел VI. API как продукт/04.md b/src/ru/clean-copy/07-Раздел VI. API как продукт/04.md index 74a9cb3..17f0874 100644 --- a/src/ru/clean-copy/07-Раздел VI. API как продукт/04.md +++ b/src/ru/clean-copy/07-Раздел VI. API как продукт/04.md @@ -10,7 +10,7 @@ * в частности, разработчики скептически относятся к громким рекламным заявлениям и готовы разбираться в том, насколько эти заявления соответствуют истине; - * к разработчикам крайне сложно обращаться через стандартные маркетинговые каналы; помимо того, что они получают информацию в основном из ускоспециализированных сообществ, программисты также смотрят в первую очередь на мнения, подтверждённые конкретными цифрами и примерами (желательно — примерами кода); + * к разработчикам крайне сложно обращаться через стандартные маркетинговые каналы; помимо того, что они получают информацию в основном из узкоспециализированных сообществ, программисты также смотрят в первую очередь на мнения, подтверждённые конкретными цифрами и примерами (желательно — примерами кода); * мнения «инфлюэнсеров» в такой среде значат очень мало, поскольку ничьё мнение не принимается на веру; diff --git a/src/ru/clean-copy/07-Раздел VI. API как продукт/06.md b/src/ru/clean-copy/07-Раздел VI. API как продукт/06.md index 97c7c6d..0fead4d 100644 --- a/src/ru/clean-copy/07-Раздел VI. API как продукт/06.md +++ b/src/ru/clean-copy/07-Раздел VI. API как продукт/06.md @@ -16,7 +16,7 @@ #### Вертикальное разделение сервисов API -Часто, однако, имеет смысл предоставлять несколько сервисов API, оперирующих одной и той же функциональностью. Напомним, что все разработчики делятся на две категории — профессионалов, которые ищут возможности глубокой кастомизации (поскольку работают в крупных ИТ-компаниях со сложившимся подходом к разработке), и начинающих разработчиков, которым необходим максимально заниженный порог входа. Максимально полно покрыть нужды обеих групп можно только разработав множество продуктов с разным порогом входа и требовательностью к профессиональному уровню программиста. Можно выделить следующие подвиды API, по убыванию требуемого уровня разработчиков. +Часто, однако, имеет смысл предоставлять несколько сервисов API, оперирующих одной и той же функциональностью. Напомним, что все разработчики делятся на две категории — профессионалов, которые ищут возможности глубокой кастомизации (поскольку работают в крупных ИТ-компаниях со сложившимся подходом к разработке), и начинающих разработчиков, которым необходим максимально заниженный порог входа. Максимально полно покрыть нужды обеих групп можно только разработав множество продуктов с разным порогом входа и требовательностью к профессиональному уровню программиста. Можно выделить следующие подвиды API, по убыванию требуемого уровня разработчиков. 1. Самый сложный уровень — физического API и семейства абстракций над ними. [В нашем кофейном примере — та часть интерфейсов, которая описывает работу с физическим API кофе машин, см. главу [«Разделение уровней абстракции»](#api-design-separating-abstractions) и главу [«Слабая связность»](#back-compat-weak-coupling).] 2. Базовый уровень — работы с продуктовыми сущностями через формальные интерфейсы. [В случае нашего учебного API этому уровню соответствует HTTP API заказа.] 3. Упростить работу с продуктовыми сущностями можно, предоставив SDK для различных платформ, скрывающие под собой сложности работы с формальными интерфейсами и адаптирующие концепции API под соответствующие парадигмы (что позволяет разработчикам, знакомым только с конкретной платформой, не тратить время и не разбираться в формальных интерфейсах и протоколах). diff --git a/src/ru/drafts/03-Раздел II. Паттерны дизайна API/10.md b/src/ru/drafts/03-Раздел II. Паттерны дизайна API/10.md index 5cc774f..4c3928b 100644 --- a/src/ru/drafts/03-Раздел II. Паттерны дизайна API/10.md +++ b/src/ru/drafts/03-Раздел II. Паттерны дизайна API/10.md @@ -87,7 +87,7 @@ PATCH /v1/orders/{id} * наконец, подобная наивная концепция организации совместного доступа работает ровно до того момента, пока изменения транзитивны, т.е. результат не зависит от порядка выполнения операций (в нашим примере это уже не так — операции удаления первого элемента и редактирования первого элемента нетранзитивны); * кроме того, часто в рамках той же концепции экономят и на входящем трафике, возвращая пустой ответ сервера для модифицирующих операций; таким образом, два клиента, редактирующих одну и ту же сущность, не видят изменения друг друга. -**Более консистентное решение**: разделить эндпойнт на несколько идемпотентных суб-эндпойнтов. Этот подход также хорошо согласуется с принципом декомпозиции, который мы рассматривали в предыдущем главе [«Разграничение областей ответственности»](#api-design-isolating-responsibility). +**Более консистентное решение**: разделить эндпойнт на несколько идемпотентных суб-эндпойнтов. Этот подход также хорошо согласуется с принципом декомпозиции, который мы рассматривали в предыдущем главе [«Разграничение областей ответственности»](#api-design-isolating-responsibility). ``` // Создаёт заказ из двух напитков diff --git a/src/ru/l10n.json b/src/ru/l10n.json index 9ea2295..662a660 100644 --- a/src/ru/l10n.json +++ b/src/ru/l10n.json @@ -13,7 +13,7 @@ "title": "Об авторе", "content": [ "

Сергей Константинов работает с API уже больше десятилетия. Он начинал свою карьеру разработчиком в подразделении API Яндекс.Карт, и со временем стал руководителем всего сервиса, отвечая и за техническую, и за продуктовую составляющую.

", - "

За это время Сергей получил уникальный опыт построения API мирового уровня с дневной аудторией в десятки миллионов человек, планирования роадмапов для такого продукта и многочисленных публичных выступлений. Он также проработал полтора года в составе Технической архитектурной группы W3C.

", + "

За это время Сергей получил уникальный опыт построения API мирового уровня с дневной аудиторией в десятки миллионов человек, планирования роадмапов для такого продукта и многочисленных публичных выступлений. Он также проработал полтора года в составе Технической архитектурной группы W3C.

", "

После девяти лет в Картах Сергей переключился на технические роли в других департаментах и компаниях, занимаясь интеграционными проектами и будучи ответственным за техническую архитектуру целых продуктов компании. Сегодня Сергей живёт в Таллинне, Эстония, и работает ведущим инженером в компании Bolt.

" ], "imageCredit": "Фото: Denis Hananein" @@ -74,7 +74,7 @@ "title": "API", "pageTitle": "Титульный лист", "contents": [ - "

«API-first» подход — одна из самых горячих горячих тем в разработке программного обеспечения в наше время. Многие компании начали понимать, что API выступает мультипликатором их возможностей — но также умножает и допущенные ошибки.

", + "

«API-first» подход — одна из самых горячих тем в разработке программного обеспечения в наше время. Многие компании начали понимать, что API выступает мультипликатором их возможностей — но также умножает и допущенные ошибки.

", "

Эта книга написана для того, чтобы поделиться опытом и изложить лучшие практики разработки API. Книга состоит из шести разделов, посвящённых:

", "