Изяснете задачата и решението
Това ръководство превръща бързия старт на api в прегледан оперативен работен процес. Той свързва решения за домейн, собственост, доказателства и приемане, така че резултатът да продължи да работи в производството.
Започнете с една удостоверена заявка, валидирайте договора за отговор и добавете обработка на грешки, преди да свържете CMS.
Практически процес
- 1
Типове източници на инвентаризация, идентификатори, полета, локали, собственици и състояния на публикация.
- 2
Изберете модела на доставка от обем, латентност, редакционен контрол и толерантност на отказ.
- 3
Съпоставете изходния запис към отделен запис на езикова версия с трайна връзка.
- 4
Добавете удостоверяване, идемпотентност, повторен опит, анулиране на кеша, регистриране и контроли за достъп.
- 5
Тестова публикация, промени в източника, недостъпни резултати, връщане назад, работа с клавиатура и наблюдение преди пускане.
Пример или инструмент
Пълната двойка заявка и отговор включва удостоверяване, локал, режим, идемпотентност и обработка на грешки. В инструмента запишете също базовата линия, собственика, решението, доказателствата, отворения проблем и датата на одобрение. Използвайте реална страница или транзакция, така че екипът да види зависимости, изключения и работата по поддръжката, която следва освобождаването.
| Точка на решение | Записвайте | Критерий за приемане |
|---|---|---|
| Базово ниво | Наблюдавано текущо състояние | Източник и дата на запис |
| Решение | Избран вариант и обосновка | Обмислени риск и аудитория |
| Доказателство | Тествайте, документирайте или измервайте | Възможност за преглед и специфична за версията |
| Одобрение | Име, роля и дата | Спазени всички задължителни критерии |
Изпратете една заявка във формата на производство
Създайте клиент за интеграция от страна на сървъра и съхранете неговите идентификационни данни в секретния мениджър за разполагане. Изпратете UTF-8 JSON през HTTPS със стабилен идентификатор на източника, редакция на източника, заявен локал, езиков режим и съдържание. Добавете ключ за идемпотентност, който остава същият, когато идентичната задача се опита повторно. Не излагайте идентификационни данни в кода на браузъра, файловете на хранилище, CMS полета, екранни снимки или видими от клиента отговори за грешки.
Започнете с представителна, но нечувствителна страница за услуги. Включете заглавия, списъци, връзки и правно или оперативно условие, така че отговорът да изпълнява реалния договор за съдържание. Отхвърлете празен идентификатор на източник, неподдържан локал, неизвестен режим, прекалено голямо тяло или неправилно формирана структура, преди да извикате API. Задайте изрично време за изчакване на връзката и отговора и разпространете идентификатор на корелация в регистрационните файлове на вашето приложение.
| Поле за заявка | Цел | Валидиране |
|---|---|---|
| sourceId | Устойчива връзка към записа CMS | Изисква се, стабилен, неличен |
| sourceRevision | Открива остарели резултати | Задължително и неизменно за заявката |
| локал и режим | Избира езикови правила | Трябва да е разрешена комбинация |
| idempotencyKey | Прави повторните опити безопасни | Същата операция използва същия ключ |
Валидирайте пълния договор за отговор
Третирайте успешен HTTP статус само като първа проверка. Валидирайте схемата на отговора, идентификатора на резултата, идентификатора на източника и ревизията, локала, езиковия режим, състоянието на обработка, блоковете на съдържанието, предупрежденията и версията на модела или набора от правила, където е предоставена. Неизвестните стойности на enum и липсващите задължителни полета трябва да не успеят да се затворят в грешка при интегриране, която може да бъде прегледана. Запазете предупрежденията до черновата, защото те могат да идентифицират терминология, качество на източника или изисквания за ръчен преглед.
Съхранявайте генерирания изход като отделна чернова на редакция, вместо да презаписвате одобрения източник. Идентификатори на заявка за запис и резултат, настройки за трансформация, времеви отпечатъци и хеш за цялост на изходната версия. Рендирайте разлика за рецензенти и избягвайте целия изход според местоназначението му. Генерираното маркиране е ненадежден вход, докато валидирането на схемата, дезинфекцията, проверките за достъпност и одобрението от човек не приключат.
- 1
Валидирайте изходящия полезен товар спрямо локална схема.
- 2
Изпратете заявката със заглавки за удостоверяване, изчакване, идемпотентност и корелация.
- 3
Проверете състоянието, заглавките и тялото на отговора спрямо фиксирания договор.
- 4
Създайте отделна чернова на CMS, свързана с точната версия на източника.
- 5
Насочвайте предупрежденията и разликите в правилната опашка за редакционен преглед.
Отстранявайте грешките без дублиране или загуба на работа
Време за изчакване на повторен опит, неуспешна връзка и ограничения на скоростта само когато операцията е идемпотентна. Използвайте ограничено експоненциално забавяне с трептене и спазвайте предоставеното от сървъра забавяне при повторен опит. Не опитвайте повторно неуспешно валидиране, неуспешно удостоверяване или неподдържани опции, докато конфигурацията не се промени. Поставете изчерпаните операции в опашка за мъртви писма с препратка към източника, безопасна категория на грешката, брой опити и следващия отговорен екип.
Отделете състоянието, изправено пред потребителя, от диагностичните детайли. Редакторите се нуждаят от ясни състояния като на опашка, обработка, готова чернова, изисква се действие и неуспешно с безопасна следваща стъпка. Операциите се нуждаят от идентификатори на заявки, продължителност, категория на състоянието и хронология на повторните опити, но не и пълния изходен текст в обикновените регистрационни файлове. Предупреждение за постоянен процент грешки, нарастваща възраст на опашката, грешки при удостоверяване, несъответствия на схеми и чернови, чиято ревизия на източника се е променила по време на обработката.
Всяка повторна операция има стабилен ключ за идемпотентност.
Отстъпването е ограничено и спазва инструкциите за ограничение на скоростта.
Дневниците изключват идентификационни данни и ненужни тела на съдържание.
Елементите с мъртво писмо имат собственик и процедура за повторение.
Остарял резултат не може тихо да замени по-нова ревизия на източника.
Докажете интеграцията преди пускане
Тествайте валидни заявки, всяка документирана грешка при валидиране, изтекли и отменени идентификационни данни, изчаквания, ограничения на скоростта, дублиране на подаване, завършване извън реда, развитие на схемата, дезинфекция и промени на източника по време на обработка. Уверете се, че мониторингът идентифицира всеки отказ и че обучен оператор може да повтори или затвори елемента без редактиране на базата данни. Изпълнете достъпност и редакционен преглед на изобразената чернова, а не само на необработения отговор.
Пускане с ограничени идентификационни данни, дефинирана скорост и лимити на разходите, табла за управление, собственост на предупреждения и превключвател за връщане назад, който спира ново генериране, без да засяга публикуваното съдържание. Закачете поддържаната версия на договора и насрочете преглед на надстройката. Записът за приемане на продукцията трябва да включва доказателство за тестване, одобрение за сигурност, документация за потока от данни, подписване от рецензент, инструкции за работа и успешно възстановяване на една умишлено неуспешна работа.
Роли, доказателства и одобрение
Съхранявайте генерирането отделно от публикуването. Успешният отговор е чернова, а не одобрение. Съхранявайте идентификатора на източника и версията, настройките за трансформация, идентификатора на резултата, състоянието на прегледа, одобряващия и времето за публикуване. Когато източникът се промени, маркирайте езиковата версия за преглед, вместо тихо да замествате одобреното съдържание. Това прави възможно връщане назад и одит на различни платформи.
Експлоатация и поддръжка
Работата не приключва с публикуването. Свържете езиковата версия или конфигурация с нейния източник, наблюдавайте мерките за качество и обслужване и дефинирайте конкретни тригери за преглед. Задействанията включват промени в източника, правни промени, нови нужди на аудиторията, повтарящи се въпроси за поддръжка, технически промени и инциденти. Посочен собственик оценява тригера, отваря нова ревизия, когато е необходимо, и записва подновено одобрение.
Контролен списък за публикуване
Интеграцията използва трайни идентификатори на източника.
Идентификационните данни се съхраняват от страната на сървъра и се сменят.
Дефинирани са изчакване, повторен опит и поведение при ограничаване на скоростта.
Повтарящите се искания са идемпотентни.
Генерираното съдържание влиза в състояние на преглед.
Промените в източника обезсилват или отварят отново версията.
Езиковата навигация работи с клавиатура и помощна технология.
Мониторингът обхваща повреди, опашки, забавяне и остаряло съдържание.