API може да започне како чист контролер, уредна датотека со рути и неколку познати обрасци. Тоа е лесниот дел. Потешкото прашање доаѓа подоцна: кога клиент ќе пријави збунувачки резултат, услуга надолу по текот ќе се расипе по промена или инженерот на дежурство треба да разбере зошто едно навидум безопасно барање е скапо.

Одржливите API не се дефинирани според тоа колку малку шаблонски код содржат. Тие се дефинирани според тоа дали тимот може безбедно да ги разбира, менува, управува и подобрува со текот на времето. Тоа го прави дизајнот на API подеднакво проблем на лидерство и сопственост, како и програмерски проблем.

Започнете со граница на производот, а не со листа на крајни точки

Тимовите често ја започнуваат работата на API со претворање на табели од база на податоци или екрани во рути. Тоа може да биде корисно за внатрешни прототипови, но ретко создава траен јавен договор. Потрошувачите не размислуваат во смисла на табела наречена orders; тие размислуваат во смисла на задачи: поставување нарачка, проверка на нејзиниот статус, исправка на адреса за испорака или усогласување плаќање.

Посилна почетна точка е да се опише исходот за корисникот и деловното правило зад него. На пример, „откажи нарачка“ не е едноставно менување поле за статус. Можеби треба да одбие веќе испратени нарачки, да забележи кој го иницирал откажувањето, да ослободи залиха и да извести други системи. Крајната точка е само видливиот раб на таа одлука.

Ова врамување им помага на тимовите да избегнат два вообичаени неуспеси: изложување внатрешни структури на податоци како трајни договори и создавање крајни точки чии имиња се јасни, но чие однесување не е.

Прашања што вреди да се разрешат пред имплементацијата

• Кој е потрошувачот и која задача се обидува да ја заврши?
• Што мора да биде точно пред операцијата да успее?
• Кои промени на состојбата, несакани ефекти и известувања може да следат?
• Кои детали се доволно стабилни за да се ветат надворешно?
• Како ќе се опорави потрошувачот ако барањето истече или се повтори?

Овие прашања се размислување за производот во техничка форма. Тие го претвораат API од транспортен слој во намерно управувана способност.

Направете ја сопственоста видлива и конкретна

„Тимот за платформата е сопственик на API“ често е премногу нејасно за да биде корисно. Сопственоста треба да одговори на практични прашања: кој одлучува дали промената е компатибилна, кој одговара кога интеграцијата не успее, кој ја одржува документацијата и кој има овластување да повлече крајна точка?

Најдобриот модел на сопственост не е оној во кој еден постар инженер знае сè. Тој е оној во кој одговорноста е јасна, знаењето е споделено и тимот има сигурен начин за донесување одлуки. Именуван тим-сопственик може да одржува запис во каталогот на услуги, патека за поддршка, оперативни контролни табли и кратка изјава за целта и потрошувачите на API.

За оддалечен тим, оваа јасност е уште поважна. Нејаснотијата што може да се разреши во брз разговор во канцеларија, инаку може да стане недела колебливи пораки. Запишете ги одлуките што ќе им бидат потребни на идните придонесувачи: политика за верзионирање, конвенции за грешки, очекувања за автентикација, класификација на податоци и патеки за ескалација.

Дизајнирајте договори за промени, а не само за денешниот одговор

Договорот на API е ветување. Откако друга апликација ќе зависи од поле во одговорот или од однесување, неговото менување може да чини многу повеќе отколку што чинело неговото додавање. Ова не значи дека договорите мора засекогаш да бидат замрзнати. Значи дека промените бараат намерна стратегија за компатибилност.

Кога е можно, претпочитајте дополнителен развој. Ново незадолжително поле обично е полесно за потрошувачите да го толерираат отколку преименувано поле или променето значење. Бидете внимателни со стандардните вредности: изоставен параметар во барање што тивко добива ново однесување може да биде исто толку нарушувачки како отстрането својство.

Обработката на грешки заслужува иста грижа како и успешните одговори. На клиентот му е потребна доволно структура за да одлучи дали да го исправи внесот, да побара корисникот да дејствува, да се обиде повторно подоцна или да извести оператор. Избегнувајте да ги терате клиентите да анализираат проза за да ја донесат таа одлука.

{
  "error": {
    "code": "ORDER_NOT_CANCELLABLE",
    "message": "This order can no longer be cancelled.",
    "details": {
      "status": "shipped"
    }
  }
}

Точната форма е помалку важна од доследноста и документацијата. Ако операцијата може безбедно да се повтори, кажете го тоа. Ако клиентите треба да користат клуч за идемпотентност за операција на создавање, дефинирајте го неговиот опсег и однесувањето при задржување. Нејасната политика за повторни обиди повикува на дупликати плаќања, дупликати е-пораки и тешки истраги.

Вградете ја повратната врска во испораката

Документацијата не е последен чекор на доработка. Таа е еден од најбрзите начини да се открие дали интерфејсот има смисла. Ако развивачот не може да објасни како да се автентицира, да направи прво барање, да протолкува неуспех и да мигрира од постаро однесување, API не е подготвен за широка употреба.

Корисната API документација е ориентирана кон задачи. Таа вклучува примери што наликуваат на вистински барања, објаснува важни ограничувања и го разликува стабилното однесување на договорот од деталите на имплементацијата. Кога е практично, одржувајте ги примерите проверени според договорот; застарените примери создаваат повеќе работа за поддршка отколку отсутните.

На тимовите им е потребна и повратна информација од продукција. Следете ги сигналите што го одразуваат искуството на потрошувачите: категории на грешки, доцнење по операција, неуспеси на зависности, невообичаен обем на барања и усвојување нови верзии или полиња. Самите метрики не се сопственост, но ја прават сопственоста применлива. Растечката стапка на грешки при валидација може да открие збунувачка документација. Налет од повторни обиди може да открие ненадежна зависност или нејасна политика за истекување на време.

Прегледувајте ги промените на API како промени на производот

Прегледот на барање за повлекување треба да оди подалеку од именување и форматирање. Прашајте што ќе забележат постојните потрошувачи. Разгледајте невалиден внес, неуспеси на овластување, делумни прекини на зависности, истовремени барања, повторни обиди, граници на пагинација и празни резултати. За промени со значајно влијание врз потрошувачите, обезбедете кратка белешка за миграција пред издавањето, наместо по инцидент.

Практична листа за проверка пред издавање може да вклучува:

• ажурирања на договорот и документацијата;
• проценка на компатибилноста за постојните потрошувачи;
• тестови за очекувани неуспеси, како и за успешни патеки;
• евидентирање и следење на новото однесување;
• сопственик и план за комуникација за воведување или повлекување.

Дајте им простор на развивачите да преземат сопственост над исходите

Техничкото лидерство не е чин на одобрување на секоја одлука. Тоа е создавање услови добрите одлуки да се случуваат повторливо. Развивачите напредуваат кога можат да разберат проблем на клиентот, да обликуваат договор, да ги видат неговите оперативни ефекти и да го подобрат по издавањето.

Тоа бара граници. Тимот не може одговорно да поседува API ако друга група може да го промени неговото однесување без координација, или ако прашањата за поддршка исчезнуваат во општа редица. Во исто време, сопственоста не треба да стане изолација. Заедничките стандарди за автентикација, набљудливост и одговор на инциденти ја намалуваат непотребната варијација, додека тимовите остануваат одговорни за сопствените одлуки во доменот.

Оваа рамнотежа е особено вредна за развојот на кариерата. Инженерите што учат да размислуваат за договори, влијание врз клиентите, сигурност и компромиси стануваат поефективни од инженерите што оптимизираат само локални детали на имплементацијата. Кодот и понатаму е важен; тој едноставно е дел од поголемо ветување.

API е долготраен разговор

Шаблонскиот код може брзо да направи новата услуга да изгледа завршена. Одржливата испорака поставува позахтевно прашање: дали овој тим може да го продолжи разговорот со своите потрошувачи кога барањата се менуваат, се случуваат неуспеси и производот расте?

Градете API околу јасни исходи. Именувајте ги луѓето одговорни за нив. Третирајте ги договорите, документацијата и операциите како дел од производот. Кога овие навики се воспоставени, API станува повеќе од збирка крајни точки. Станува сигурна граница што им овозможува на тимовите брзо да се движат без секоја идна промена да ја прават преговор со минатото.