Referência de Transforms

A API em https://transforms.nimbusnexus.net/v1 cria, versiona, testa e executa pipelines, apenas para o seu workspace. Requisições e respostas são JSON. Envie uma chave como Authorization: Bearer <key> ou X-API-Key: <key> (Como obter acesso). Os timestamps são ISO 8601 em UTC. A visão geral explica o produto, e Pipelines, o documento.

Rotas

read, write e admin são explicados em Quem pode fazer o quê.

As listas são paginadas com limit (de 1 a 200, padrão 50) e offset (de 0 a 10,000). A resposta é {"items": [...], "next_offset": <offset>}: passe next_offset de volta como offset para obter a próxima página. Ele é null na última página. GET /v1/pipelines/templates é a exceção: essa rota não recebe limit nem offset e responde com todos os templates em um único array simples.

O objeto pipeline

POST /v1/pipelines recebe name e pipeline. Um documento que nunca conseguiria rodar é recusado com 422 invalid_pipeline e, acima dos pipelines do plano, a resposta é 402 quota_exceeded, com details.metric pipelines, details.limit e details.current.

Versões

PATCH /v1/pipelines/{id} recebe qualquer um de name, status e pipeline. Um pipeline novo é verificado como na criação e salvo como a próxima versão.

• Uma versão nunca muda, então um produto pode guardar a própria cópia pelo id e pela versão.
• Salvar o mesmo conteúdo não adiciona nenhuma versão.
• Restaurar uma versão antiga é salvar o conteúdo dela de novo, o que faz dele a versão mais recente.
• As versões do plano são mantidas, começando pelas mais recentes, e um salvamento remove as mais antigas além desse número. Uma versão que um produto fixa também é mantida, assim como as cinco versões anteriores que um produto foi visto executando mais recentemente nos últimos 30 dias.

Cada versão em GET /v1/pipelines/{id}/versions tem version, created_by e created_at; GET /v1/pipelines/{id}/versions/{version} acrescenta o pipeline dela. Uma versão que já não é mantida responde 404 not_found, pipeline_version.

Executar um pipeline

POST /v1/pipelines/{id}/run executa a versão atual, ou a versão mantida que version indica, sobre o que você envia:

Nada da requisição é guardado, e a execução é contada. A resposta é um 200, independentemente do que o pipeline tenha feito:

O mesmo pipeline com a mesma requisição falha do mesmo jeito, então não tente de novo um failed. Um pipeline desativado responde 409 conflict, pipeline_disabled, e acima da taxa do plano, ou com execuções ou testes demais do workspace em andamento ao mesmo tempo, uma execução responde 429 rate_limited, com details.retry_after.

Testar um documento

POST /v1/pipelines/test recebe pipeline, um documento que não precisa estar salvo, com body, headers e meta. Ele é verificado como em um salvamento, roda uma vez e não salva nem conta nada, embora compartilhe a taxa do plano. Um descarte ou uma falha é um 200 que diz isso.

Slots de credencial

Um slot é o que uma etapa auth indica: um id e um rótulo, sem valor. O Transforms não armazena nenhuma credencial, e nenhuma rota recebe uma. Um produto que executa o pipeline por referência associa o slot a um segredo próprio (Credenciais). POST /v1/slots recebe label, com até 200 caracteres, e responde 201:

PATCH /v1/slots/{id} recebe label. DELETE /v1/slots/{id} responde 204, ou 409 conflict, com details.reason slot_in_use, details.id e details.pipelines, o número de pipelines, enquanto a versão atual de um pipeline o indicar. Acima dos slots do plano, adicionar um responde 402 quota_exceeded, com details.metric slots.

Quem executa um pipeline

Um produto referencia um pipeline pelo id e o executa no próprio processo, com os próprios segredos. O Webhooks é o primeiro: Transformações. Toda vez que um produto obtém o pipeline, o serviço e a versão são registrados, então a leitura de um pipeline mostra destinations e consumers.

Salvar uma nova versão com uma etapa auth alcança todos os produtos que executam o pipeline, e excluí-lo também. Cada uma dessas chamadas precisa indicar em confirm_destinations todos os serviços que têm uma referência ou foram vistos nos últimos 30 dias, no corpo de um PATCH e na query de um DELETE. Caso contrário, a resposta é um 409 conflict com details.reason destinations_unconfirmed e details.destinations, e nada muda. As próprias URLs de um serviço nunca aparecem aqui: esse produto faz a mesma pergunta em relação a elas.

Quem pode fazer o quê

Uma ação recusada responde 403 forbidden com details.reason role, e details.required indica a função necessária. Um membro ainda pode renomear um pipeline com uma etapa de credencial, executá-lo, testá-lo e remover a etapa. O console da conta cria chaves Read e Read & write, e uma chave com qualquer outro escopo, como write, é tratada como Read.

O Transforms atende workspaces inteiros. Um assento de convidado, ou uma chave restrita a um projeto, é recusado com 403 project_confined. Um workspace tem o Transforms depois que um proprietário ou admin abre o console ou o adiciona em Add a product. Até lá, os outros membros são recusados com 403 product_not_enabled.

Planos e limites

GET /v1/plan informa quais limites se aplicam: plan, o plano registrado; enforced_as, o plano cujos limites se aplicam, free quando não há nenhum; ceilings, os limites pelo nome; past_due, suspended e system.

Até o equivalente a dez segundos de execuções, e no mínimo 10, podem chegar em rápida sucessão. Um workspace também tem no máximo duas execuções ou testes em andamento ao mesmo tempo em cada processo do servidor, e mais um é recusado, sem ir para a fila, com 429 rate_limited e details.retry_after 1. GET /v1/usage informa quanto já foi usado: period, o mês, representado pelo primeiro dia; runs, failures e dropped deste mês, pela API de execução; pipelines em relação a max_pipelines; e slots, os slots existentes, em relação a max_secret_slots. As execuções são contadas, não cobradas, e uma execução em um produto que referencia o pipeline conta no uso desse produto.

Enquanto houver uma cobrança em aberto, as alterações são recusadas com 402 workspace_frozen, e as execuções e os testes continuam. Depois que o período de carência termina, as execuções e os testes também são recusados, com 402 workspace_suspended. As leituras e as exclusões continuam liberadas.

Erros

Os erros da API usam o formato descrito em Erros.

Pipelines inválidos

A recusa indica o primeiro problema: details.reason, details.path (um JSON Pointer até ele) e details.step (contado a partir de 0), cada um quando se aplica.

{ "error": { "code": "invalid_pipeline", "message": "…", "details": { "reason": "credential_header", "path": "/steps/0/headers/set/Authorization", "step": 0 }, "request_id": "…" } }

Trate reason como uma string aberta e mantenha um caso padrão para um valor que você não conhece.

Próximos passos

• Início rápido — teste um pipeline, salve-o e execute-o.
• Pipelines — todas as etapas, caminhos, filtros e templates.
• API de Transforms — todas as operações, com a requisição em curl, TypeScript, Python ou Go.
• Erros — o formato do erro, todas as chaves de details e um padrão para tratá-los.