Как написать api для приложения
Начнём с рассмотрения того что представляют собой API на высоком уровне и выясним, как они работают, как их использовать в своих программах и как они структурированы. Также рассмотрим основные виды API и их применение.
| Необходимые знания: | Базовая компьютерная грамотность, понимание основ HTML и CSS, основы JavaScript (см. первые шаги, building blocks, объекты JavaScript). |
|---|---|
| Цель: | Познакомиться с API, выяснить что они могут делать и как их использовать. |
Что такое API?
Интерфейс прикладного программирования (Application Programming Interfaces, APIs) - это готовые конструкции языка программирования, позволяющие разработчику строить сложную функциональность с меньшими усилиями. Они "скрывают" более сложный код от программиста, обеспечивая простоту использования.
Для лучшего понимания рассмотрим аналогию с домашними электросетями. Когда вы хотите использовать какой-то электроприбор, вы просто подключаете его к розетке, и всё работает. Вы не пытаетесь подключить провода напрямую к источнику тока — делать это бесполезно и, если вы не электрик, сложно и опасно.
Точно также, если мы хотим, например, программировать 3D графику, гораздо легче сделать это с использованием API, написанных на языках высокого уровня, таких как JavaScript или Python.
Note: Смотрите также API в словаре.
API клиентской части JavaScript
Для JavaScript на стороне клиента, в частности, существует множество API. Они не являются частью языка, а построены с помощью встроенных функций JavaScript для того, чтобы увеличить ваши возможности при написании кода. Их можно разделить на две категории:
- API браузера встроены в веб-браузер и способны использовать данные браузера и компьютерной среды для осуществления более сложных действий с этими данными. К примеру, API Геолокации (Geolocation API) предоставляет простые в использовании конструкции JavaScript для работы с данными местоположения, так что вы сможете, допустим, отметить своё расположение на карте Google Map. На самом деле, в браузере выполняется сложный низкоуровневый код (например, на C++) для подключения к устройству GPS (или любому другому устройству геолокации), получения данных и передачи их браузеру для обработки вашей программой, но, как было сказано выше, эти детали скрыты благодаря API.
- Сторонние API не встроены в браузер по умолчанию. Такие API и информацию о них обычно необходимо искать в интернете. Например, Twitter API позволяет размещать последние твиты (tweets) на вашем веб-сайте. В данном API определён набор конструкций, осуществляющих запросы к сервисам Twitter и возвращающих определённые данные.
Взаимодействие JavaScript, API и других средств JavaScript
Итак, выше мы поговорили о том, что такое JavaScript API клиентской части и как они связаны с языком JavaScript. Давайте теперь тезисно запишем основные понятия и определим назначение других инструментов JavaScript:
- JavaScript — Язык программирования сценариев высокого уровня, встроенный в браузер, позволяющий создавать функциональность веб-страниц/приложений. Отметим, что JavaScript также доступен на других программных платформах, таких как Node. Но пока не будем останавливаться на этом.
- API браузера (Browser APIs) — конструкции, встроенные в браузер, построенные на основе языка JavaScript, предназначенные для облегчения разработки функциональности.
- Сторонние API (Third party APIs) — конструкции, встроенные в сторонние платформы (такие как Twitter, Facebook) позволяющие вам использовать часть функциональности этих платформ в своих собственных веб-страницах/приложениях (например, показывать последние Твиты на вашей странице).
- Библиотеки JavaScript — Обычно один или несколько файлов, содержащих пользовательские (custom) функции. Такие файлы можно прикрепить к веб-странице, чтобы ускорить или предоставить инструменты для написания общего функциональности. Примеры: jQuery, Mootools и React.
- JavaScript фреймворки (frameworks) — Следующий шаг в развитии разработки после библиотек. Фреймворки JavaScript (такие как Angular и Ember) стремятся к тому, чтобы быть набором HTML, CSS, JavaScript и других технологий, после установки которого можно "писать" веб-приложение с нуля. Главное различие между фреймворками и библиотеками - "Обратное направление управления" ( “Inversion of Control” ). Вызов метода из библиотеки происходит по требованию разработчика. При использовании фреймворка - наоборот, фреймворк производит вызов кода разработчика.
На что способны API?
Широкое разнообразие API в современных браузерах позволяет наделить ваше приложение большими возможностями. Достаточно посмотреть список на странице MDN APIs index page.
Распространённые API браузера
В частности, к наиболее часто используемым категориям API (и которые мы рассмотрим далее в этом модуле) относятся :
Распространённые сторонние API
Существует множество сторонних API; некоторые из наиболее популярных, которые вы рано или поздно будете использовать, включают:
-
для добавления такой функциональности, как показ последних твитов на сайте. для работы с картами на веб-странице (интересно, что Google Maps также использует этот API). Теперь это целый набор API, который может справляться с широким спектром задач, как свидетельствует Google Maps API Picker. позволяет использовать различные части платформы Facebook в вашем приложении, предоставляя, например, возможность входа в систему с логином Facebook, оплаты покупок в приложении, демонстрация целевой рекламы и т.д. , предоставляющий возможность встраивать видео с YouTube на вашем сайте, производить поиск, создавать плейлисты и т.д. - фреймворк для встраивания функциональности голосовой и видео связи в вашем приложении, отправки SMS/MMS из приложения и т.д.
Note: вы можете найти информацию о гораздо большем количестве сторонних API в Каталоге Web API.
Как работает API?
Работа разных JavaScript API немного отличается, но, в основном, у них похожие функции и принцип работы.
Они основаны на объектах
Взаимодействие с API в коде происходит через один или больше объектов JavaScript, которые служат контейнерами для информации, с которой работает API (содержится в свойствах объекта), и реализуют функциональность, которую предоставляет API (содержится в методах объекта).
Note: Если вам ещё не известно как работают объекты, советуем вернуться назад и изучить модуль Основы объектов JavaScript прежде чем продолжать.
Вернёмся к примеру с API Геолокации — очень простой API, состоящий из нескольких простых объектов:
-
, содержит три метода для контроля и получения геоданных. , предоставляет данные о местоположении устройства в заданный момент времени — содержит Coordinates - объект, хранящий координаты и отметку о текущем времени. , содержит много полезной информации о расположении устройства, включая широту и долготу, высоту, скорость и направление движения и т.д.
Так как же эти объекты взаимодействуют? Если вы посмотрите на наш пример maps-example.html (see it live also), вы увидите следующий код:
Note: Когда вы впервые загрузите приведённый выше пример, появится диалоговое окно, запрашивающее разрешение на передачу данных о местонахождении этому приложению (см. раздел У них есть дополнительные средства безопасности там, где это необходимо далее в этой статье). Вам нужно разрешить передачу данных, чтобы иметь возможность отметить своё местоположение на карте. Если вы всё ещё не видите карту, возможно, требуется установить разрешения вручную; это делается разными способами в зависимости от вашего браузера; например, в Firefox перейдите > Tools > Page Info > Permissions, затем измените настройки Share Location; в Chrome перейдите Settings > Privacy > Show advanced settings > Content settings и измените настройки Location.
Во-первых, мы хотим использовать метод Geolocation.getCurrentPosition() , чтобы получить текущее положение нашего устройства. Доступ к объекту браузера Geolocation производится с помощью свойства Navigator.geolocation , так что мы начнём с
Это эквивалентно следующему коду
Но мы можем использовать точки, чтобы связать доступ к свойствам/методам объекта в одно выражение, уменьшая количество строк в программе.
Метод Geolocation.getCurrentPosition() имеет один обязательный параметр - анонимную функцию, которая запустится, когда текущее положение устройства будет успешно считано. Сама эта функция принимает параметр, являющийся объектом Position (en-US) , представляющим данные о текущем местоположении.
Note: Функция, которая передаётся другой функции в качестве параметра, называется колбэк-функцией (callback function).
Такой подход, при котором функция вызывается только тогда, когда операция была завершена, очень распространён в JavaScript API — убедиться, что операция была завершена прежде, чем пытаться использовать данные, которые она возвращает, в другой операции. Такие операции также называют асинхронными операциями (asynchronous operations). Учитывая, что получение данных геолокации производится из внешнего устройства (GPS-устройства или другого устройства геолокации), мы не можем быть уверены, что операция считывания будет завершена вовремя и мы сможем незамедлительно использовать возвращаемые ею данные. Поэтому такой код не будет работать:
Если первая строка ещё не вернула результат, вторая вызовет ошибку из-за того, что данные геолокации ещё не стали доступны. По этой причине, API, использующие асинхронные операции, разрабатываются с использованием callback function, или более современной системы промисов, которая появилась в ECMAScript 6 и широко используются в новых API.
Мы совмещаем API Геолокации со сторонним API - Google Maps API, который используем для того, чтобы отметить расположение, возвращаемое getCurrentPosition() , на Google Map. Чтобы Google Maps API стал доступен на нашей странице, мы включаем его в HTML документ:
Чтобы использовать этот API, во-первых создадим объект LatLng с помощью конструктора google.maps.LatLng() , принимающим данные геолокации Coordinates.latitude (en-US) и Coordinates.longitude (en-US) :
Этот объект сам является значением свойства center объекта настроек (options), который мы назвали myOptions . Затем мы создаём экземпляр объекта, представляющего нашу карту, вызывая конструктор google.maps.Map() и передавая ему два параметра — ссылку на элемент <div> , на котором мы хотим отрисовывать карту (с ID map_canvas ), и объект настроек (options), который мы определили выше.
Когда это сделано, наша карта отрисовывается.
Последний блок кода демонстрирует два распространённых подхода, которые вы увидите во многих API:
- Во-первых, объекты API обычно содержат конструкторы, которые вызываются для создания экземпляров объектов, используемых при написании программы.
- Во-вторых, объекты API зачастую имеют несколько вариантов (options), которые можно настроить и получить именно ту среду для разработки, которую вы хотите. API конструкторы обычно принимают объекты вариантов (options) в качестве параметров, с помощью которых и происходит настройка.
Note: Не отчаивайтесь, если вы что-то не поняли из этого примера сразу. Мы рассмотрим использование сторонних API более подробно в следующих статьях.
У них узнаваемые точки входа
При использовании API убедитесь, что вы знаете где точка входа для API. В API Геолокации это довольно просто — это свойство Navigator.geolocation , возвращающее объект браузера Geolocation , внутри которого доступны все полезные методы геолокации.
Найти точку входа Document Object Model (DOM) API ещё проще — при применении этого API используется объект Document , или экземпляр элемента HTML, с которым вы хотите каким-либо образом взаимодействовать, к примеру:
Точки входа других API немного сложнее, часто подразумевается создание особого контекста, в котором будет написан код API. Например, объект контекста Canvas API создаётся получением ссылки на элемент <canvas> , на котором вы хотите рисовать, а затем необходимо вызвать метод HTMLCanvasElement.getContext() :
Всё, что мы хотим сделать с canvas после этого, достигается вызовом свойств и методов объекта содержимого (content) (который является экземпляром CanvasRenderingContext2D ), например:
Note: вы можете увидеть этот код в действии в нашем bouncing balls demo (see it running live also).
Они используют события для управления состоянием
Мы уже обсуждали события ранее в этом курсе, в нашей статье Introduction to events — в этой статье детально описываются события на стороне клиента и их применение. Если вы ещё не знакомы с тем, как работают события клиентской части, рекомендуем прочитать эту статью прежде, чем продолжить.
Следующий код содержит простой пример использования событий:
Note: вы можете увидеть этот код в действии в примере ajax.html (see it live also).
Затем функция-обработчик onload определяет наши действия по обработке ответа сервера. Нам известно, что ответ успешно возвращён и доступен после наступления события load (и если не произойдёт ошибка), так что мы сохраняем ответ, содержащий возвращённый сервером объект JSON в переменной superHeroes , которую затем передаём двум различным функциям для дальнейшей обработки.
У них есть дополнительные средства безопасности там, где это необходимо
К тому же, некоторые WebAPI запрашивают разрешение от пользователя, как только к ним происходит вызов в коде. В качестве примера, вы, возможно, встречали такое диалоговое окно при загрузке нашего примера Geolocation ранее:
Notifications API запрашивает разрешение подобным образом:
Запросы разрешений необходимы для обеспечения безопасности пользователей — не будь их, сайты могли бы скрытно отследить ваше местоположение, не создавая множество надоедливых уведомлений.
Итоги
На данном этапе, у вас должно сформироваться представление о том, что такое API, как они работают и как вы можете применить их в своём JavaScript-коде. Вам наверняка не терпится начать делать по-настоящему интересные вещи с конкретными API, так вперёд! В следующий раз мы рассмотрим работу с документом с помощью Document Object Model (DOM).
Я разработчик и большую часть моей карьеры я строю API различных сервисов. Рекомендации для этой статьи были собраны на основе наиболее часто встречающихся проблем при проектировании своего сервиса в команде или использовании сторонних API.
Скорее всего, вы сталкивались с провайдерами ужасного API. Работа с ними, как правило, сопряжена c повышенной эмоциональностью и недопониманием. Большую часть таких проблем можно избежать, проектируя интерфейс приложения, используя советы ниже.
1. Не используйте глаголы в URL *
* - если это одна из CRUD-операций.
За действие с ресурсом отвечают CRUD-методы запроса: POST - создать (create), GET - получить (read), PUT/PATH - обновить (update), DELETE - удалить (ну вы поняли). Плохо:
Хорошо:
2. Используйте глаголы в URL
Плохо:
Хорошо:
3. Выделяйте новые сущности
Выше есть пример добавления книги пользователю, возможно, логика вашего приложения подразумевает список избранного, тогда роут может быть и таким:
4. Используйте один идентификатор ресурса *
* - если ваша структура данных это позволяет.
Это значит если у вас есть записи вида один ко многим, например
бронь -> путешественники (booking->travellers), вам будет достаточно передавать в запросе идентификатор путешественника.
Плохо:
Хорошо:
Также замечу, что /bookings/travellers/ лучше, чем просто /travellers . Хорошо придерживаться иерархии данных в своем API.
5. Все ресурсы во множественном числе
Плохо:
Хорошо:
400 Bad Request - клиент отправил неверный запрос, например, отсутствует обязательный параметр запроса.
401 Unauthorized - клиенту не удалось пройти обязательную аутентификацию на сервере для обработки запроса.
403 Forbidden - клиент аутентифицирован, но не имеет разрешения на доступ к запрошенному ресурсу.
404 Not Found - запрошенный ресурс не существует.
409 Conflict - этот ответ отправляется, когда запрос конфликтует с текущим состоянием сервера.
500 Internal Server Error - на сервере произошла общая ошибка.
503 Service Unavailable - запрошенная услуга недоступна.
7. Модификаторы получения ресурса
Логика построения роутов может быть не связана с архитектурой проекта или структурой базы данных. Например, в бд есть викторины и пройденные викторины - две отдельные таблицы (quizzes и passed_quizzes). Но для апи это могут быть просто викторины, а пройденные викторины это модификатор.
Пример: /quizzes и /quizzes/passed . Здесь quizzes - ресурс (викторины), passed - модификатор (пройденные).
Плохо:
Хорошо:
Когда на два запроса к API может быть получен совсем разный по структуре ответ - это грустно. Старайтесь сформировать одну четкую структуру, которой всегда будете придерживаться. Будет круто еще включить служебные поля, несущие дополнительную информацию.
Плохо:
Хорошо:
9. Все параметры и json в camelCase
9.1 В параметрах запросов
Плохо:
Хорошо:
9.2 В теле ответа или принимаемого запроса
Плохо:
Хорошо:
10. Пользуйтесь Content-Type
Плохо:
Хорошо:
Заключение
А в комментариях предлагаю написать свою рекомендацию по построению REST API, которую вы считаете важной.
Планируете начать работу над новым веб-приложением? В этом руководстве мы обсудим, как создать веб-приложение, ориентированное на API, и объясним, почему это важно в современном многоплатформенном мире.
Ищете ярлык?
Если вам нужно быстрое решение, ознакомьтесь с одним из элементов API в Envato Market, например API Framework , который позволяет вам создать собственный API в кратчайшие сроки. Фреймворк очень прост в использовании и расширяется, если у вас есть знания PHP и ООП.
Или вы можете попробовать Any API для HTML с сервисом PHP на Envato Studio. Если вы заказываете эту услугу, вы можете анализировать любой API со сторонних веб-сайтов и показывать результаты на своем веб-сайте с вашим макетом и функциями.
Вступление
Что такое API-ориентированное веб-приложение?
Зачем переживать все эти неприятности?
Как веб-разработчики, мы видели, как технологии развиваются из первых рук. Общеизвестно, что сегодня люди используют приложения не только через браузер, но и через другие гаджеты, такие как мобильные телефоны и планшеты. Например, в этой статье на Mashable, озаглавленной «Потребители теперь тратят больше времени на мобильные приложения, чем в Интернете» , говорится:
В новом отчете утверждается, что потребители тратят больше времени на мобильные приложения, чем на Интернет.
Flurry сравнил свои мобильные данные со статистикой comScore и Alexa и обнаружил, что в июне потребители тратили 81 минуту в день, используя мобильные приложения, по сравнению с 74 минутами веб-серфинга.
Какое это имеет отношение к созданию веб-приложения, ориентированного на API?
Это неизбежно приведет к большему использованию нашего приложения, поскольку оно может использоваться везде, где хочет человек.
Одним из основных преимуществ создания приложения, ориентированного на API, является то, что оно помогает создавать функциональные возможности, которые могут использоваться ЛЮБЫМ устройством, будь то браузер, мобильный телефон, планшет или даже настольное приложение. Все, что вам нужно сделать, это создать API таким образом, чтобы все эти устройства могли общаться с ним, и вуаля! Вы создадите централизованное приложение, которое может принимать и выполнять функции с любого устройства, которое есть у человека!
API-ориентированная прикладная диаграмма
Создавая приложение таким образом, мы можем легко использовать преимущества различных средств, используемых разными людьми. Это неизбежно приведет к большему использованию приложения, поскольку оно может использоваться везде, где хочет человек.
В этом руководстве мы создадим простое приложение со списком TODO, ориентированное на API, и создадим в браузере одного клиентского интерфейса, который взаимодействует с нашим приложением со списком TODO. В итоге вы узнаете неотъемлемые части приложения, ориентированного на API, и в то же время узнаете, как обеспечить безопасную связь между ними. Имея это в виду, давайте начнем!
Шаг 1. Планирование функций приложения
Приложение TODO, которое мы будем создавать в этом руководстве, будет иметь основные функции CRUD:
- Создать элементы TODO
- Читать ТОДО
- Обновить элементы TODO (переименовать, пометить как выполненное, пометить как отмененное)
- Удалить элементы TODO
Каждый предмет TODO будет иметь:
Давайте также макетируем приложение, чтобы у нас было руководство о том, как оно должно выглядеть потом:
Шаг 2. Создайте сервер API
Поскольку мы разрабатываем приложение, ориентированное на API, мы будем создавать два «проекта»: сервер API и клиент переднего плана . Начнем с создания сервера API.
Другим разработчиками действительно придётся использовать API, который ты напишешь. Поэтому здесь нельзя лажать. Если не хочешь, чтобы полчища разъярённых программистов с факелами и вилами осадили твой дом посреди ночи, то проектируй API правильно.
Здесь приведены несколько советов по разработке, которые я перенял от коллег за прошедшие годы. Они применимы ко всем видам API: будь то библиотеки с открытым кодом, внутренние SDK, модули или даже единственный класс.
Это, пожалуй, самый важный совет. Если у тебя есть метод под названием getUser и он делает что-то неявное, да ещё и умалчивает о таком поведении — это может привести к множеству проблем.
Не изменяй значения общих переменных, не оговаривая это. Если я вызываю getUser , то ожидаю, что он просто вернёт пользователя. А не увеличит, в процессе, user_id на 1 . Прими во внимание неизменяемые структуры данных.
Имя метода/класса/модуля должно нести как можно больше смысла о том, что он делает. В разумных пределах, конечно. Не жди, что пользователи будут нырять в код в поисках скрытого поведения, о котором не говорит имя. Таким образом, ты избавишь себя от головной боли в дальнейшем.
Никто не любит раздутые программы. Чем меньше API ты открываешь для выполнения задачи, тем будет лучше для всех.
Кто-то действительно просит этот новый API, который ты хочешь написать? Может стоит его отложить до тех пор, пока это действительно не станет проблемой, которую кто-то хочет решить.
В некоторых средах разработки, таких как Android, существуют жёсткие ограничения на общее количество методов, которые могут быть у приложения. Так что имей это ввиду, если нацелен на такие платформы.
Преждевременное выполнение в ответе за умопомрачительную растрату часов программирования. Применяй YAGNI.
Как можно больше деталей реализации должны обрабатываться внутри, чтобы уменьшить нагрузку на клиентов. Чем меньше потребитель должен делать, тем меньше возможное количество ошибок, с которыми ты потом будешь сталкиваться.
В этом также состоит вопрос эстетики. Использование шаблонного кода может разрушить вполне хороший API, и потребительский код будет выглядеть безобразно. Мы все любим чистый код, не так ли? Облегчи потребителям задачу сделать код лаконичным и чистым при использовании твоего API.
Стремись к тому, чтобы твой код был автономным насколько это возможно. Чем больше у него зависимостей, тем больше проблем это может вызвать в потребительском коде.
Если ты действительно хочешь тот красивый кусочек функциональности из другого модуля, попробуй извлечь его и включить только то, что тебе нужно.
Уравновесить возможность повторного использования кода и тесную связь всегда непросто. Тебе придётся принять такое решение. Если эта функциональность невелика, возможно стоит переписать её самому.
Я мог бы целый день разглагольствовать о том, что null — это бесполезная конструкция. Она буквально означает ничего.
“Эй, модуль, дай мне пользователя”
“Неа. Вот тебе вместо этого ничего”
Если в твоём языке отсутствуют исключения, радуйся! В любом случае, тип Either и его когорты, встречающиеся в функциональных языках, гораздо лучше в предоставлении осмысленных состояний ошибки.
Исключениями, как правило, склонны злоупотреблять в мире Java. Исключения созданы для обработки действительно исключительных случаев. Ты действительно не ожидал, что getUser может не найти пользователя? Не выкидывай UserNotFoundException . Вместо этого, возвращай подходящее состояние ошибки.
Впрочем, при реальной неудаче, лучше потерпеть её быстро.
“Единственное, что может быть хуже падающей программы — программа, которая не падает и продолжает работать в неопределённом состоянии.”
Документация — это скучно. И, как многие скучные вещи, очень важна. Хорошая документация спасёт твою психику. Ты сможешь избежать постоянных вопросов от потребителей твоего API, что само по себе расценивается на вес золота.
Хорошая документация должна состоять из:
- Описание модуля на верхнем уровне, и как он работает
- Публичные методы и протоколы описанные в Javadocs, Heredocs, Rdocs или т.п.
- Пример кода, показывающий как его использовать.
Не все абстракции требуют одного и того же уровня документации. Небольшому классу, например, не нужен пример кода.
Документация также должна эволюционировать. Если ты получаешь кучу вопросов об одном и том же, то можешь добавить это в документацию для будущих потребителей.
Слишком много документации также является пустой тратой времени. Так как это создаёт ещё один актив, который нужно держать в актуальном состоянии. И у него не будет никакой ценности, если его никто не использует.
Однако, целенаправленная и соответствующая документация — это всегда полезно.
Тесты — это доказательство правильности, документация и пример кода в одном флаконе. Они несут огромную ценность при рефакторинге и позволяют тебе двигаться быстро и уверенно, когда ты что-нибудь меняешь.
Потребители, которые хотят глубже вникнуть в твою реализацию, всегда могут прочитать тесты, чтобы больше узнать о цели и внутреннем поведении кода. Документация не может охватить всё, и вот тут помогают тесты.
“Зачем тогда вообще писать документацию, если у меня есть тесты?” — можешь спросить ты. Позволю себе такую отдалённую аналогию: если документация, это руководство пользователя к твоему API, тогда тесты — это инструкция под опкод x86.
Тестирование своего собственного кода — это одно. Написать API, который с лёгкостью позволит тестировать свой код тем, кто его использует— совсем другое. API, которые трудно имитировать / использовать как заглушку в тест-кейсах, будут отталкивать разработчиков, уделяющих внимание тестам.
Ты можешь использовать параметры конфигурации для версий отладки и релиза, где это возможно. Зачастую, некоторые вещи должны вести себя по-разному в условиях Непрерывной интеграции / развёртывания, нежели чем в продакшене. Обрати на это внимание.
Каждый потребитель захочет использовать твой API по-своему. Одни захотят чтобы он работал синхронно. Другие предпочтут асинхронные обратные вызовы (callback), future, promise или Rx observable.
Позволь потребителям выбирать то, что они хотят, на сколько это возможно. Чем проще твой API интегрируется в их существующую программную и системну среду, тем более вероятно, что люди будут использовать его.
Не давай потребителям слишком широкий простор для выбора, чтобы в итоге их не охватил аналитический паралич. Всегда стремись обеспечить осмысленные значения по умолчанию. Большую часть времени, твой API будет использован определённым образом. Так пусть дефолтные настройки обеспечивают такое поведение.
API должен поощрять каноническое поведение. Не позволяй потребителям изменить какие-то случайные параметры в твоём модуле, если это не часть функционала. Если ты откроешь какое-то непреднамеренное поведение — можешь быть уверен, что когда-нибудь оно будет использовано, порождая непредсказуемые последствия.
Будь упрямым. Не теряй фокус, давая слишком много вариантов. Способность выбрать между верным количеством опций и верной степенью гибкости требует практики и опыта. Если сомневаешься: заблуждение на той стороне, где меньше вариантов.
Проектирование API — это искусство. Будем надеяться, что советы, изложенные здесь, помогут тебе в написании лучшего кода. Вероятно, я упустил много других вещей, но эти служили мне хорошо. Живи и учись.
Читайте также: