Контекст
Системные API разрабатываются, в том числе и так, чтобы попытаться решить несовместимые задачи. Например, следующие задачи – предоставить возможность детального управления ресурсом системы, и в то же время, упростить работу с ресурсом для разработчика. Такие задачи/цели порождают, например, следующее системное противоречия – API должно быть минимальным для того, чтобы можно было им легко/безопасно/с минимальным количеством ошибок использоваться, и в то же время, API должно быть детальным для того, чтобы можно было использовать максимум возможностей для управления системными ресурсами.
Последнее противоречие в системном API может:
не разрешаться вообще (это происходит, например, если цель разработки в минимизации затрат ресурсов системы во время выполнения кода);
разрешаться частично (с помощью, например, несколько уровней API или предоставлением нескольких/ряда системных API адаптированных под свои подзадачи);
разрешаться с помощью развития API дополнительными адаптирующими библиотеками (например, адаптирующие под возможности более мощных языков).
С другой стороны при разработке ad hoc для конкретного(ых) проекта(ов) можно получить бонусы разработки с помощью адаптации системного(ых) API под нужны данного проекта и данной команды разработчиков.
Например, можно получить следующие преимущества:
выделение наиболее важной для данного проекта части API;
выделение нескольких уровней API (выделение нескольких уровней детализации API) с точки зрения данного проекта (разработчик в большинстве случаев может использовать простейший уровень API и только в отдельных случаях использовать более сложные и более детальные глубокие уровни API);
интеграция системного API с существующей инфраструктурой проекта;
сокрытие части действий с системным API от разработчиков данного проекта, за счёт того, что мы знаем для данного проекта корректное поведение по умолчанию с системным API;
за счёт реализации по умолчанию некоторых стандартных операций, которые единообразны для данного проекта;
использование преимуществ инфраструктуры (языков, других библиотек, средств интеграции и так далее) данного проекта для развития системного API с целью улучшения качества использования API разработчиками проекта;
и так далее.
Прием
Так как одной из наиболее важных целей адаптации системного API и создания внутреннего API для конкретного проекта является повышение качества/повышение скорости/оптимизации уровня вхождения разработки, то предлагается следующее.
На этапе проектирования API создавать код и примеры использования будущего API и начинать с проектирования использования будущего внутреннего API.
Это означает, пробовать писать работающий код заглушек API, который можно скомпилировать и выполнить для разработки интерфейса использования API. Пробовать разные варианты того, как можно использовать системный API в рамках вашей адаптации для вашего проекта для ваших разработчиков. Пробовать проводить code review примеров использования будущего внутреннего API. Пробовать выяснять возможные точки развития вашего внутреннего API, осознавать то, как воспринимается внутреннее API вашими разработчиками, оценивать удобство использования внутреннего API для ваших разработчиков.
Важно, чтобы это был хоть и код заглушек, но вполне компилируемый и вполне выполняемый код. Код, который можно рассматривать на code review. Чтобы можно было просить разработчиков попробовать использовать ваше внутреннее API, ещё на стадиях проектирования API.