Esclareça a tarefa e a decisão
Este guia transforma o início rápido da API em um fluxo de trabalho operacional revisável. Ele conecta decisões de domínio, propriedade, evidências e aceitação para que o resultado continue funcionando na produção.
Comece com uma solicitação autenticada, valide o contrato de resposta e adicione o tratamento de falhas antes de conectar o CMS.
Processo prático
- 1
Tipos de origem de inventário, identificadores, campos, localidades, proprietários e estados de publicação.
- 2
Escolha o padrão de entrega entre volume, latência, controle editorial e tolerância a falhas.
- 3
Mapeie o registro de origem para um registro de versão de idioma separado com ligação durável.
- 4
Adicione autenticação, idempotência, nova tentativa, invalidação de cache, registro em log e controles de acesso.
- 5
Publicação de testes, alterações de origem, resultados indisponíveis, reversão, operação do teclado e monitoramento antes do lançamento.
Exemplo ou ferramenta
Um par completo de solicitação e resposta inclui autenticação, localidade, modo, idempotência e tratamento de erros. Na ferramenta, registre também a linha de base, o proprietário, a decisão, as evidências, a questão em aberto e a data de aprovação. Use uma página ou transação real para que a equipe veja dependências, exceções e o trabalho de manutenção que segue o lançamento.
| Ponto de decisão | Registro | Critério de aceitação |
|---|---|---|
| Linha de base | Estado atual observado | Fonte e data registrada |
| Decisão | Opção selecionada e justificativa | Risco e público considerados |
| Evidência | Teste, documente ou meça | Revisável e específico da versão |
| Aprovação | Nome, função e data | Todos os critérios obrigatórios atendidos |
Envie uma solicitação em formato de produção
Crie um cliente de integração do lado do servidor e armazene sua credencial no gerenciador de segredo de implementação. Envie JSON UTF-8 por HTTPS com um identificador de origem estável, revisão de origem, localidade solicitada, modo de idioma e corpo de conteúdo. Adicione uma chave de idempotência que permaneça a mesma quando o trabalho idêntico for repetido. Não exponha credenciais no código do navegador, arquivos de repositório, campos CMS, capturas de tela ou respostas de erro visíveis ao cliente.
Comece com uma página de serviço representativa, mas não confidencial. Inclua títulos, listas, links e uma condição legal ou operacional para que a resposta exerça o verdadeiro contrato de conteúdo. Rejeite um identificador de origem vazio, localidade não suportada, modo desconhecido, corpo superdimensionado ou estrutura malformada antes de chamar API. Defina uma conexão explícita e um tempo limite de resposta e propague um identificador de correlação nos logs do seu aplicativo.
| Campo de solicitação | Propósito | Validação |
|---|---|---|
| ID de origem | Link durável para o registro CMS | Obrigatório, estável, não pessoal |
| fonteRevisão | Detecta resultados obsoletos | Obrigatório e imutável para a solicitação |
| localidade e modo | Seleciona regras de idioma | Deve ser uma combinação habilitada |
| chave de idempotência | Torna as tentativas seguras | A mesma operação usa a mesma chave |
Valide o contrato de resposta completo
Trate um status HTTP bem-sucedido apenas como a primeira verificação. Valide o esquema de resposta, identificador de resultado, identificador e revisão de origem, localidade, modo de idioma, status de processamento, blocos de conteúdo, avisos e versão do modelo ou conjunto de regras, quando fornecido. Valores enum desconhecidos e campos obrigatórios ausentes devem falhar e resultar em um erro de integração revisável. Preserve avisos ao lado do rascunho porque eles podem identificar terminologia, qualidade da fonte ou requisitos de revisão manual.
Armazene a saída gerada como uma revisão de rascunho separada, em vez de substituir a fonte aprovada. Registre identificadores de solicitação e resultado, configurações de transformação, carimbos de data/hora e um hash de integridade da revisão de origem. Renderize uma comparação para revisores e escape de todos os resultados de acordo com seu destino. A marcação gerada é uma entrada não confiável até que a validação do esquema, a higienização, as verificações de acessibilidade e a aprovação humana sejam concluídas.
- 1
Valide a carga de saída em relação a um esquema local.
- 2
Envie a solicitação com cabeçalhos de autenticação, tempo limite, idempotência e correlação.
- 3
Valide o status, os cabeçalhos e o corpo da resposta em relação ao contrato fixado.
- 4
Crie um rascunho CMS separado vinculado à revisão de origem exata.
- 5
Encaminhe avisos e diferenças para a fila de revisão editorial correta.
Lide com erros sem duplicar ou perder trabalho
Tempos limite de repetição, falhas de conexão e limites de taxa somente quando a operação for idempotente. Use espera exponencial limitada com jitter e respeite um atraso de nova tentativa fornecido pelo servidor. Não tente novamente falhas de validação, falhas de autenticação ou opções não suportadas até que a configuração seja alterada. Coloque as operações esgotadas em uma fila de mensagens mortas com a referência de origem, categoria de erro seguro, contagem de tentativas e próxima equipe responsável.
Separe o estado voltado para o usuário dos detalhes de diagnóstico. Os editores precisam de estados claros, como em fila, em processamento, rascunho pronto, ação necessária e falha na próxima etapa segura. As operações precisam de identificadores de solicitação, duração, categoria de status e histórico de novas tentativas, mas não do texto fonte completo em logs comuns. Alerta sobre taxa de erros sustentada, aumento da idade da fila, falhas de autenticação, incompatibilidades de esquema e rascunhos cuja revisão de origem foi alterada durante o processamento.
Cada operação repetível possui uma chave de idempotência estável.
A retirada é limitada e respeita as instruções de limite de taxa.
Os logs excluem credenciais e corpos de conteúdo desnecessários.
Itens de letras mortas têm um proprietário e um procedimento de repetição.
Um resultado obsoleto não pode substituir silenciosamente uma revisão de origem mais recente.
Prove a integração antes do lançamento
Teste solicitações válidas, todos os erros de validação documentados, credenciais expiradas e revogadas, tempos limite, limites de taxa, envio duplicado, conclusão fora de ordem, evolução de esquema, higienização e alterações de origem durante o processamento. Confirme se o monitoramento identifica cada falha e se um operador treinado pode reproduzir ou fechar o item sem editar o banco de dados. Execute a revisão editorial e de acessibilidade no rascunho renderizado, em vez de apenas na resposta bruta.
Lance com uma credencial restrita, taxas definidas e limites de gastos, painéis, propriedade de alertas e um switch de reversão que interrompe a nova geração sem afetar o conteúdo publicado. Fixe a versão do contrato compatível e agende uma revisão de atualização. O registro de aceitação da produção deve incluir evidências de teste, aprovação de segurança, documentação de fluxo de dados, aprovação do revisor, instruções de operação e a restauração bem-sucedida de um trabalho deliberadamente falho.
Funções, evidências e aprovação
Mantenha a geração separada da publicação. Uma resposta bem-sucedida é um rascunho, não uma aprovação. Armazene o identificador de origem e a versão, as configurações de transformação, o identificador de resultado, o estado de revisão, o aprovador e o horário de publicação. Quando a fonte for alterada, marque a versão do idioma para revisão em vez de substituir silenciosamente o conteúdo aprovado. Isso torna possível a reversão e a auditoria em todas as plataformas.
Operações e manutenção
O trabalho não termina na publicação. Vincule a versão ou configuração do idioma à sua origem, monitore medidas de qualidade e serviço e defina gatilhos de revisão concretos. Os gatilhos incluem alterações na fonte, alterações legais, novas necessidades do público, dúvidas recorrentes de suporte, alterações técnicas e incidentes. Um proprietário nomeado avalia o gatilho, abre uma nova revisão quando necessário e registra a aprovação renovada.
Lista de verificação para publicação
A integração usa identificadores de origem duráveis.
As credenciais são armazenadas no servidor e rotacionadas.
O comportamento de tempo limite, nova tentativa e limite de taxa são definidos.
Solicitações repetidas são idempotentes.
O conteúdo gerado entra em estado de revisão.
As alterações na origem invalidam ou reabrem a versão.
A navegação por idioma funciona por teclado e tecnologia assistiva.
O monitoramento cobre falhas, filas, latência e conteúdo obsoleto.