books/The-API-Book
1
0
Fork 0
mirror of https://github.com/twirl/The-API-Book.git synced 2025-02-10 18:31:34 +02:00
Code Issues Releases Activity

Rethinking

Browse Source
This commit is contained in:
Sergey Konstantinov 2019-10-30 22:14:56 +03:00
parent d47934e264
commit de4adec826
2 changed files with 37 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
API.ru.html
View File

@ -2,63 +2,26 @@
<html><head>
<meta charset="utf-8"/>
<title>API</title>
<style>
body {
width: 60%;
max-width: 1000px;
margin: 10px auto 0 300px;
font-family: Georgia, serif;
font-size: 16px;
}
header {
text-align: center;
}
h1, h2, h3, h4 {
font-weight: bold;
margin: 0;
padding: 0.2em 0 0.2em 0;
}
</style>
<link rel="stylesheet" href="style.css"/>
</head><body>
<header>
<h1>Сергей Константинов</h1>
<h1>API</h1>
<img src="Why.jpg" style="height: 600px;"/>
</header>
<h2>Об авторе</h2>
<h2>Введение</h2>
<p>Если мы посмотрим на определение из энциклопедии, то узнаем, что программирование — это что-то вроде преобразования формально проставленной задачи в исполняемый код, как правило, путём имплементации какого-то алгоритма на определённом языке программирования. И действительно, курсы обучения соответствующим дисциплинам большей частью и состоят из инструкций, как перевести словесно поставленную задачу в код и запрограммировать тот или иной алгоритм.</p>
<p>Прежде чем говорить о разработке API, необходимо для начала договориться о том, что же такое API. Энциклопедия скажет нам, что API — это программный интерфейс приложений. Это точное определение, но бессмысленное. Примерно как определение человека по Платону: «двуногое без перьев» — определение точное, но никоим образом не дающее нам представление о том, чем на самом деле человек примечателен. (Да и не очень-то и точное: Диоген Синопский как-то ощипал петуха и заявил, что это человек Платона; пришлось дополнить определение уточнением «с плоскими ногтями».)</p>
<p>Этот алгоритмический подход — пожалуй, худшее, что могло случиться с программистами. Определять программирование через имплементацию алгоритмов — это как определять работу композитора как написание специальных значков на нотном стане, математика — как написание формул, астронома — как смотрение в телескоп.</p>
<p>Что же такое API по смыслу, а не по формальному определению?</p>
<p>Чем плохи эти определения? Тем, что они описывают лишь формальную сторону процесса, оставляя за кадром главный вопрос: зачем? Зачем программисты пишут код, математики - формулы, композиторы - ноты? Математики увеличивают сумму человеческих знаний, композиторы высекают своей музыкой искры из людских сердец, а вот зачем программисты пишут свои алгоритмы?</p>
<p>Вероятно, вы сейчас читаете эту книгу посредством браузера. Чтобы браузер смог отобразить эту страничку, должны корректно отработать: разбор URL согласно спецификации; служба DNS; соединение по протоколу TLS; передача данных по протоколу HTTP; разбор HTML-документа; разбор CSS-документа; корректный рендеринг HTML+CSS.</p>
<p>Почему я придаю этому вопросу столь большое значение? Потому что методы решения задачи и использованные инструменты в первую очередь должны быть адекватны используемой задаче, а всё остальное вторично. Именно цель написания кода должна определять такие первичные вещи, как архитектура приложения, используемый язык разработки и выбор инструментария. Я прочитал немалое количество книг по профессиональной разработке программного обеспечения - и не нашел качественного освещения этого вопроса ни в одной из них. Все они рассказывают, как писать "хороший" код - поддерживаемый, расширяемый, безошибочный; но опускают при этом вопрос о том, насколько написание "хорошего" кода адекватно стоящим перед разработчиками целям. Между тем, мировая практика такова, что ставит под большое сомнение предположение, что хороший код означает качественный или хотя бы поддерживаемый и расширяемый продукт. Легко привести множество примеров удачных продуктов, написанных откровенно плохо и с нарушением всех мыслимых заповедей разработки.</p>
<p>Но это только верхушка айсберга. Для работы HTTP необходима корректная работа всего сетевого стека, который состоит из 4-5, а то и больше, протоколов разных уровней. Разбор HTML-документа производится согласно сотням различных спецификаций. Рендеринг документа обращается к нижележащему API операционной системы, а также напрямую к API видеокарты. И так далее, и тому подобное — вплоть до того, что наборы команд современных CISC-процессоров имплементируются поверх API микрокоманд.</p>
<p>Хочу ли я тем самым сказать, будто бы нужно писать плохой код? Нет, что вы - на протяжении всей этой книги я буду призывать вас писать хороший код. Я хочу сказать, что, если мы посмотрим на разработку программных продуктов через призму вопроса "зачем" (они разрабатываются), то поймём, что качество решения задач пользователей само по себе не проистекает из следования советам по написанию хорошего кода - это совершенно отдельное качество продукта, и думать о нём также необходимо отдельно.</p>
<p>Иными словами, десятки, если не сотни, различных API должны отработать корректно для выполнения простейших действий типа просмотра web-страницы; без надёжной работы каждого из них современные информационные технологии попросту не могли бы существовать.</p>
<h3>Об API и уровнях восприятия</h3>
<p>У любопытного читателя может возникнуть вопрос: хорошо, мы поняли интенцию относительно соответствия принципов разработки программного обеспечения её целям. При чем же здесь API? Позвольте объяснить.</p>
<p>Программирование как трансляция формальной задачи с человеческого языка на машинный — это первый (скорее даже, нулевой) уровень восприятия процесса разработки. Нет алгоритма, который был бы как остров, сам по себе; каждый алгоритм откуда-то берётся и для чего-то предназначен. Иными словами, существует некоторый контекст, в котором будет работать этот небольшой фрагмент программного кода. В первую очередь таким контекстом является программный продукт целиком, в составе которого имплементируется алгоритм.</p>
<p>Чем больше, масштабнее и сложнее программный продукт, тем менее важна собственно алгоритмизация конкретной подзадачи и тем более важна архитектура продукта в целом. Правильно ли произведена декомпозиция? Будет ли этот код понятен другому разработчику через несколько лет? Можно ли потом эффективно расширять и поддерживать этот код?</p>
<p>Это следующий уровень восприятия проекта: понимание <em>контекста</em> существования конкретного фрагмента кода. На этом уровне появляется понимание того, что интерфейс должен быть сначала спроектирован, и что с ним надо «переспать», т.е. всесторонне обдумать; что «переключение контекстов» — дорогая операция, и что браться за другую задачу в другом проекте, на самом деле, очень сложно, даже если требуется написать всего 10 строчек кода.</p>
<p>Но и этот уровень не последний. Помимо контекста внутри программного продукта существует также и ещё более широкий контекст — внешний, в котором живёт сам продукт. Связи внешнего мира с внутренним миром разработки широки и разнообразны: внешний мир определяет функциональность продукта, внешний мир диктует свои правила. Помимо прямой связи существует и обратная: кто-то во внешнем мире будет пользоваться вашим продуктом и, возможно, вашим программным кодом — т.е. вы сами привносите нечто во внешний контекст, и это «нечто» какое-то время будет там жить.</p>
<p>API - это ничто иное, как средство связи контекстов. Например, когда вы реализуете какой-то алгоритм — вы используете API языка программирования. Компилятор языка программирования, в свою очередь, использует API команд процессора. Это API, в случае CISC-процессоров, в свою очередь построено поверх ещё более низкоуровнего API микрокоманд; и так далее. Только представьте себе, какое огромное количество API разных уровней должно отработать — и отработать правильно! — для того, чтобы вы смогли, скажем, увидеть страничку в браузере: тут и весь сетевой стек с его 6-7 уровнями абстракции; и серверное ПО — веб-сервер, генерация страницы, база данных, кэш; и клиентское ПО — браузер — имплементирующее буквально десятки разных API.</p>
<p>В современном мире роль API трудно преувеличить, и она продолжает расти. Всё новые и новые устройства — от часов и розеток до кораблей и ветряных турбин — включаются в «игру контекстов» и обзаводятся своим API. При этом, к сожалению, качество этих API всё больше оставляет желать лучшего.</p>
<p>В отличие от прикладного кода, которым будут пользоваться только ваши коллеги, разработка API подразумевает, что вашими программными интерфейсами будут пользоваться другие разработчики. Именно поэтому в разработке API проблемы, описанные в предыдущем разделе, стоят особенно остро. Хорошее API должно одновременно быть и качественно реализовано, и качественно спроектировано с точки зрения предоставляемых интерфейсов.</p>
<p>Цель написания этой книги - посмотреть на разработку программного обеспечения под другим углом, дополнить известные принципы разработки программных продуктов принципами разработки API.</p>
<p>API — <em>это обязательство</em>. Формальное обязательство связывать между собой различные программируемые контексты.</p>
<h3>Об относительности критериев качества</h3>
<p>Несмотря на всё написанное выше, я вовсе не призываю вас подходить к каждой задаче с дополнительными наборами требований. Вовсе даже наоборот: я скорее призываю эти требования сокращать.</p>
@ -73,19 +36,9 @@
<p>Есть ещё один момент, который хочется подчеркнуть: инструменты должны соответствовать конкретным обстоятельствам — предметной области, планируемому жизненному циклу продукта и, что немаловажно, компетенциям команды. Во многих случаях неидеальный инструмент, с которым команда привыкла работать, предпочтительнее неидеального, который придётся осваивать по ходу.</p>
<h3>API как универсальный паттерн</h3>
<p>На фоне сказанного выше этот заголовок должен вызывать некоторые сомнения. Универсального паттерна не существует, разве нет?</p>
<p>Тем не менее, API таковым паттерном является. Чтобы пояснить этот парадокс, давайте для начала поймём, что такое API.</p>
<p>В первом разделе мы говорили о том, что API — это связь, интерфейс взаимодействия двух программируемых контекстов. Вспомним, что мы живём в мире, очень сильно завязанном на правильное взаимодействие целых иерархий таких контекстов. Что же тогда самое важное, что такое API по смыслу?</p>
<p>API — это обязательство. Обязательство поддерживать связь контекстов. Всё остальное вторично.</p>
<h3>О структуре этой книги</h3>
<p>Книга, которую вы держите в руках, состоит из трех больших разделов, назовем их условно "статическим", "динамическим" и "маркетинговым".</p>
<p>Книга, которую вы держите в руках, состоит из трех больших разделов.</p>
<p>В первом разделе мы поговорим о проектировании API на стадии разработки концепции - как грамотно выстроить архитектуру, от крупноблочного планирования до конечных интерфейсов.</p>
@ -93,7 +46,7 @@
<p>Наконец, третий раздел будет касаться больше не-разработческих сторон жизни API - поддержки, маркетинга, достижения контакта с аудиторией.</p>
<p>Первые два будут интересны скорее разработчикам, третий - и разработчикам, и менеджерам. При этом я настаиваю, что как раз третий раздел - самый важный для разработчика API. Ввиду того, что API - продукт для разработчиков, перекладывать ответственность за его маркетинг и поддержку на не-разработчиков неправильно: никто кроме вас самих не понимает так хорошо продуктовые свойства вашего API.</p>
<p>Первые два будут интересны скорее разработчикам, третий — и разработчикам, и менеджерам. При этом я настаиваю, что как раз третий раздел — самый важный для разработчика API. Ввиду того, что API - продукт для разработчиков, перекладывать ответственность за его развитие и поддержку на не-разработчиков неправильно: никто кроме вас самих не понимает так хорошо продуктовые свойства вашего API.</p>
<h2>Проектирование API</h2>
@ -103,7 +56,7 @@
<li>определение области применения;</li>
<li>разделение уровней абстракции;</li>
<li>разграничение областей ответственности;</li>
<li>Описание конечных интерфейсов.</li>
<li>описание конечных интерфейсов.</li>
</ul>
<p>Этот алгоритм строит API сверху вниз, от общих требований и сценариев использования до конкретной номенклатуры сущностей; фактически, двигаясь этим путем, вы получите на выходе готовое API - за что мы и ценим этот подход.</p>

27
style.css Normal file
View File

@ -0,0 +1,27 @@
body {
width: 60%;
max-width: 1000px;
margin: 10px auto 0 300px;
font-family: Georgia, serif;
font-size: 18px;
}
header {
text-align: center;
background: url(Why.jpg) center 0 no-repeat;
background-size: auto;
height: 600px;
position: relative;
}
header h1 {
color: #fff;
margin: 0 20%;
}
h1, h2, h3, h4 {
font-weight: bold;
margin: 0;
padding: 0.2em 0 0.2em 0;
text-align: center;
}