Nenhuma secção encontrada.

Host-Tracker REST API v1

Uma API HTTP estável e autenticada por token para gerir tarefas de monitorização de websites, contactos, subscrições de alertas/relatórios, e para consultar estatísticas, indisponibilidades e incidentes.

URL base

Cada caminho neste documento é relativo a um URL base. Dois pontos de entrada servem a mesma API:

Ao longo desta referência, uma chamada escrita como GET tasks significa GET BASE_URL/tasks — por exemplo https://api1.host-tracker.com/tasks ou https://www.host-tracker.com/api/web/v1/tasks.

Tipo de conteúdo e métodos HTTP

Os pedidos e respostas são application/json por predefinição (ver Convenções para XML). A API utiliza os métodos HTTP padrão:

• GET — ler entidades (tarefas, contactos, subscrições, estatísticas, indisponibilidades, incidentes, agentes).
• POST — criar uma entidade ou iniciar uma ação.
• PUT — atualizar entidades existentes.
• DELETE — remover entidades.
• PATCH — atualizações parciais (utilizado para reenviar o código de confirmação de um contacto).

Substituição de método HTTP

Se o seu cliente não conseguir enviar PUT, DELETE ou PATCH, envie um POST e adicione um cabeçalho X-HTTP-Method-Override a indicar o verbo pretendido. Por exemplo, para atualizar tarefas, faça POST para tasks com X-HTTP-Method-Override: PUT.

Convenções

Serialização JSON

O JSON utiliza nomes de propriedades em camelCase. Os campos nulos são omitidos das respostas (os arrays vazios continuam a ser devolvidos como []). A ordenação das propriedades é estável: identificador e endereço/url primeiro, depois os campos herdados, depois os campos específicos do tipo.

Data e hora

As respostas de criação/leitura de tarefas transportam as datas como strings ISO-8601 UTC (por exemplo 2024-06-21T22:26:23Z). Os endpoints de estatísticas, indisponibilidades, incidentes e resultados utilizam adicionalmente uma representação dupla: cada momento aparece tanto como um campo inteiro em segundos Unix (sufixo Unix) como uma string legível formatada de acordo com o formato de data e o fuso horário do perfil da conta. Os filtros dos pedidos aceitam segundos Unix e/ou strings formatadas, consoante o endpoint (documentado por endpoint abaixo). Todos os timestamps Unix são segundos desde 1970-01-01T00:00:00Z.

Negociação de conteúdo XML

Todos os endpoints também podem devolver XML. Envie Accept: application/xml para receber um corpo XML em vez de JSON; a resposta utiliza a representação clássica do XmlSerializer do .NET para o mesmo grafo de objetos. JSON é o formato predefinido e recomendado.

CORS

Os pedidos cross-origin são permitidos. Os pedidos simples (sem credenciais) são aceites de qualquer origem (Access-Control-Allow-Origin: *). Os pedidos que enviam cookies/credenciais só são aceites a partir de origens *.host-tracker.com. Os clientes baseados em token (utilizando o cabeçalho Authorization, conforme documentado aqui) não são afetados pela restrição de origem com credenciais.

Autenticação

Todos os endpoints, exceto POST users/token e os endpoints anónimos de listagem de agentes, requerem autenticação. São aceites dois esquemas:

• Token bearer — obtido a partir de POST users/token, enviado como Authorization: bearer <token>. Este é o esquema principal.
• HTTP Basic — Authorization: Basic <base64(login:password)>. As credenciais são descodificadas como ISO-8859-1. Conveniente para testes rápidos; o token bearer é preferível para automação.

POST users/token anónimo

Troca um login e uma password por um token bearer. O token é válido durante 48 horas.

Corpo do pedido

{
  "login": "your-login",
  "password": "your-password"
}

Resposta — 200 OK

{
  "ticket": "<bearer token>",
  "expirationTime": "2024-06-23T22:26:23Z",
  "expirationUnixTime": 1719181583
}

Em caso de falha, a resposta é 401 com o código de máquina IncorrectLoginOrPassword (ou AccessDenied se o acesso à API estiver desativado para a conta) e um cabeçalho WWW-Authenticate: Bearer.

Utilizar o token

GET BASE_URL/tasks HTTP/1.1
Host: api1.host-tracker.com
Accept: application/json
Authorization: bearer 3DD135...5EE510417

Personificação de subconta (forLogin)

Se uma super-conta concedeu à sua subconta acesso aos seus dados, autentique-se como a subconta mas indique o login da super-conta em forLogin. O token devolvido permite então gerir a super-conta exatamente como se os endpoints fossem chamados para a sua própria conta, sujeito aos direitos concedidos pela super-conta. Por exemplo, se esta concedeu acesso apenas de leitura às tarefas de monitorização, as chamadas GET têm sucesso mas POST/PUT/PATCH/DELETE em tarefas são rejeitadas.

# 1. Obtain an impersonation token
POST BASE_URL/users/token HTTP/1.1
Content-Type: application/json

{
  "login": "subaccount-login",
  "password": "subaccount-password",
  "forLogin": "superaccount-login"
}

# 2. Use the returned ticket to read the SUPER-account's tasks
GET BASE_URL/tasks HTTP/1.1
Authorization: bearer <ticket from step 1>

curl

# fetch a token and store it
TOKEN=$(curl -s -X POST https://api1.host-tracker.com/users/token \
  -H "Content-Type: application/json" \
  -d '{"login":"your-login","password":"your-password"}' \
  | grep -o '"ticket":"[^"]*"' | cut -d'"' -f4)

# call an authenticated endpoint
curl -s https://api1.host-tracker.com/tasks \
  -H "Authorization: bearer $TOKEN"

Erros e códigos de máquina

Os erros devolvem um código de estado HTTP normal, mais um código legível por máquina curto no qual a sua integração se pode basear. O corpo é uma descrição em texto simples em inglês (não JSON), destinada a humanos/registos.

O código de máquina é entregue de duas formas:

• Cabeçalho de resposta X-HT-Reason — transporta o código em todas as respostas e em todas as versões de HTTP. Esta é a forma recomendada de detetar o tipo de erro.
• Frase de motivo (reason phrase) HTTP/1.1 — a linha de estado lê-se, por exemplo, HTTP/1.1 400 SimilarExists. Mantida por compatibilidade com versões anteriores, mas note que o HTTP/2 e o HTTP/3 removeram as reason phrases do protocolo, pelo que este campo pode estar vazio quando a ligação negoceia HTTP/2+. Prefira X-HT-Reason.

HTTP/1.1 400 SimilarExists
X-HT-Reason: SimilarExists
Content-Type: text/plain; charset=utf-8

Same task allready exists

Referência de códigos de erro

Todos os códigos de máquina que a API pode devolver, agrupados por área, com o código de estado HTTP típico. Salvo indicação em contrário, os erros são 400 Bad Request.

Autenticação

Tarefas

Contactos

Subscrições

Limites de taxa

Os pedidos são limitados por cliente e por endpoint. Exceder um limite devolve 429 com o código de máquina RequestThrottled e um cabeçalho Retry-After (segundos).

HTTP/1.1 429 RequestThrottled
X-HT-Reason: RequestThrottled
Retry-After: 1
Content-Type: application/json; charset=utf-8

"API calls quota exceeded! maximum admitted 6 per s."

Tarefas de monitorização

GET tasks/types

Devolve o array de nomes de tipos de tarefa que o sistema conhece:

["API","CntCheck","Counter","DNSBL","Database","DomainExp","Http",
 "Ping","Port","RusRegBL","SSLExp","Snmp","Tran","Waterfall","WebRisk"]

GET tasks/intervals

Devolve o array de intervalos de monitorização (em minutos) aceites para a sua conta, por exemplo [1,5,15,30,60]. Utilize um destes valores no campo interval ao criar uma tarefa; qualquer outro valor devolve WrongInterval.

GET tasks

Lista tarefas de monitorização. Todos os parâmetros de consulta são opcionais; sem nenhum, são devolvidas todas as tarefas da conta. Repita um parâmetro para passar um array, por exemplo ?ids=guid1&ids=guid2.

O parâmetro info

Pede dados extra incorporados em cada tarefa. Combine valores com vírgulas (?info=stats,subscriptions) ou indique o inteiro de bitmask equivalente:

?info=stats,subscriptions,results equivale a ?info=7.

Parâmetros de filtro

Resposta — 200 OK

Um array de objetos de tarefa. Os campos exatos dependem do tipo de tarefa; a base comum inclui id, name, taskType, enabled, interval, lastState, creationTime, tags, agentPools e (quando pedido via info) subscriptions, stats, results e attached. Quando os resultados são incluídos, cada resultado transporta pelo menos timestamp (segundos Unix UTC) e eventNumber; os restantes campos são específicos do tipo de tarefa (ver a resposta de criação abaixo para o formato HTTP).

GET BASE_URL/tasks?info=stats,subscriptions&taskType=Http HTTP/1.1
Accept: application/json
Authorization: bearer <token>

GET tasks/{id:guid}

Obtém uma única tarefa pelo id. Aceita o mesmo parâmetro info (e sdtu/edtu quando info=results). Devolve o objeto da tarefa, ou 404 NotFound se não existir.

POST tasks/http · tasks/ping · tasks/port · tasks/rusbl

Cria uma tarefa de monitorização do tipo indicado. Em caso de sucesso devolve 201 Created, um cabeçalho relativo Location: /tasks/{id}, e o objeto completo da tarefa criada.

Corpo do pedido — tarefa HTTP

{
  // HTTP-specific fields
  "url": "https://www.example.com",        // REQUIRED
  "httpMethod": "Get",                       // Get | Post | Head (default Get)
  "userAgent": "MyMonitor",
  "referer": "https://www.google.com",
  "acceptHeader": "application/json",
  "followRedirect": false,
  "treat300AsError": false,                // if set, followRedirect is ignored
  "checkDnsbl": false,                       // check domain against DNS block lists
  "checkDomainExpiration": false,            // monitor domain expiry (valid domains only)
  "checkCertificateExpiration": false,       // monitor TLS cert expiry (https only)
  "checkRussianBlackLists": false,
  "checkWebRisk": false,
  "timeout": 40000,                          // ms before a check fails
  "keywords": ["error", "maintenance"],
  "keywordMode": "ReverseAny",             // see keyword modes below
  "userName": "basic-auth-user",          // credentials for the monitored resource
  "password": "basic-auth-pass",
  "postParameters": "a=1\r\nb=2",          // only with httpMethod=Post
  "ignoredStatuses": [404, 500],

  // fields common to every task type
  "interval": 5,                             // minutes; must be an accepted interval
  "enabled": true,
  "fullLog": false,                          // advanced packages only
  "openStat": true,
  "name": "My website",
  "tags": ["production", "web"],
  "agentPools": ["westeurope", "asia"],  // see notes below
  "subscriptions": [ /* inline subscriptions, see below */ ]
}

Subscrições em linha

O array subscriptions subscreve contactos aos alertas/relatórios desta tarefa no momento da criação. Cada entrada utiliza o formato de subscrição; não defina taskIds (é fixado à nova tarefa). Se contactIds for omitido, todos os seus contactos confirmados são subscritos. As subscrições de relatório são aplicadas apenas a contactos de Email.

Outros tipos de tarefa

• tasks/ping — o corpo transporta host mais os campos comuns.
• tasks/port — o corpo transporta host e port mais os campos comuns.
• tasks/rusbl — verificação de lista de bloqueio do registo russo; o corpo transporta url, mais ignoreWarnings, doNotSendMsgOnWarnings, prefixMatch e os campos comuns.

Resposta — 201 Created (tarefa HTTP)

{
  "id": "ef10cd12-93f9-e311-bec5-dc85de1f0bc2",
  "url": "https://www.example.com",
  "rawUrl": "https://www.example.com",
  "name": "My website",
  "creationTime": "2024-06-21T22:26:23Z",
  "taskType": "Http",
  "enabled": true,
  "interval": 5,
  "lastState": true,
  "openStatEnabled": true,
  "fullLogEnabled": false,
  "tags": ["production", "web"],
  "agentPools": ["westeurope", "asia"],
  "subscriptions": [
    { "alertTypes": ["Up"],   "taskIds": ["ef10cd12-...-0bc2"], "contactIds": ["4cedf037-...-0bc2"] },
    { "alertTypes": ["Down"], "taskIds": ["ef10cd12-...-0bc2"], "contactIds": ["4cedf037-...-0bc2"] },
    { "reportTypes": ["Month"], "taskIds": ["ef10cd12-...-0bc2"], "contactIds": ["4cedf037-...-0bc2"] }
  ],
  "httpMethod": "Get",
  "keywords": ["error"],
  "keywordMode": "ReverseAny",
  "timeout": 40000
}

curl

curl -s -X POST https://api1.host-tracker.com/tasks/http \
  -H "Authorization: bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.example.com","interval":5,"name":"My website"}'

PUT tasks & variantes tipadas

Atualiza tarefas. Duas formas:

• Por id — PUT tasks/{id} (apenas campos comuns), ou as tipadas PUT tasks/http/{id}, tasks/ping/{id}, tasks/port/{id}, tasks/rusbl/{id} (também campos específicos do tipo). O corpo tem o mesmo formato editável da criação; só os campos que enviar são alterados.
• Por filtro — PUT tasks?<filter> (apenas campos comuns) ou a tipada PUT tasks/{type}?<filter> (que fixa o filtro a esse tipo). Utiliza os mesmos parâmetros de filtro que GET tasks. Devolve a(s) tarefa(s) atualizada(s).

O PUT tasks / PUT tasks/{id} não tipado só pode alterar campos comuns a todos os tipos de tarefa — utilize um endpoint tipado para alterar definições específicas do tipo.

DELETE tasks/{id:guid} & tasks

• DELETE tasks/{id} — apaga uma única tarefa; devolve a tarefa apagada.
• DELETE tasks?<filter> — apaga em massa pelo filtro de tarefas (o filtro também pode ser fornecido no corpo do pedido). Devolve as tarefas apagadas.

POST tasks/$batch · task/$batch

Executa vários pedidos de tarefas num único pedido. O corpo é um array JSON de sub-pedidos; a resposta é um array JSON de sub-respostas na mesma ordem. A sub-operação é escolhida pelo último segmento de relativeUrl (por exemplo, http → POST tasks/http). O corpo do pedido deve ser JSON (Content-Type: application/json). O mesmo mecanismo existe para contactos em contacts/$batch / contact/$batch.

POST BASE_URL/tasks/$batch HTTP/1.1
Authorization: bearer <token>
Content-Type: application/json

[
  {
    "method": "POST",
    "relativeUrl": "http",
    "contentType": "application/json",
    "content": "{\"url\":\"https://a.example.com\",\"interval\":5}"
  },
  {
    "method": "POST",
    "relativeUrl": "ping",
    "contentType": "application/json",
    "content": "{\"host\":\"b.example.com\"}"
  }
]

[
  { "code": 201, "status": "Created",
    "headers": { "Location": "/tasks/ef10cd12-...-0bc2" },
    "body": "{ ...created http task... }" },
  { "code": 201, "status": "Created",
    "headers": { "Location": "/tasks/7a20de34-...-1cd3" },
    "body": "{ ...created ping task... }" }
]

Contactos

Os contactos são os destinos que recebem alertas e relatórios (endereços de email, números de telefone para SMS/chamada de voz). Os ids de contacto são utilizados ao criar subscrições.

GET contacts/types · contacts/delays · contacts/sms/gateways · contacts/im/gateways

Enumerações estáticas utilizadas pelos endpoints de contactos:

GET contacts & contacts/{id:guid}

Lista contactos (opcionalmente filtrados) ou obtém um pelo id. Adicione ?info=subscriptions para incorporar as subscrições de cada contacto. Sem filtro, são devolvidos todos os contactos da conta.

Objeto de contacto

Campos comuns: id, confirmed, contactType, name, address, alertDelay, activePeriodStart/activePeriodEnd (HH:mm), activeDays, sendCost. Os contactos de email acrescentam reportFormat (Text/ShortText), sendNews, sendBillingNotifications; os contactos SMS/IM acrescentam gateway.

POST contacts/email · contacts/sms · contacts/voice

Cria um contacto. Devolve 201 Created, um Location: /contacts/{id} relativo, e um ContactOperationResult ({ contact, status }) cujo status reporta o resultado da confirmação.

{
  "address": "ops@@example.com",          // REQUIRED
  "name": "Ops mailbox",
  "alertDelay": 0,                        // minutes; one of contacts/delays
  "reportFormat": "Text",               // Text | ShortText (email only)
  "activePeriodStart": "00:00",        // optional quiet-hours window (HH:mm)
  "activePeriodEnd": "23:59",
  "activeDays": ["Monday", "Tuesday"],   // optional; default all days
  "subscriptions": [ /* optional inline subscriptions */ ]
}

Os contactos de SMS e voz utilizam por predefinição os gateways twiliosms / twiliovoice, recebem um preço por mensagem predefinido, e guardam o número com um + inicial. Alterar o endereço ou o gateway de um contacto repõe o seu estado de confirmação.

Valores de estado de confirmação

O campo status do resultado reporta o resultado do envio do código de confirmação:

PUT contacts & variantes tipadas

• Por id — PUT contacts/{id} (campos comuns), ou as tipadas PUT contacts/email/{id}, contacts/sms/{id}, contacts/voice/{id}. Só os campos que enviar são alterados.
• Por filtro — PUT contacts?<filter> ou a tipada PUT contacts/{type}?<filter> (fixa o filtro a esse tipo), utilizando o filtro de contactos.

PUT contacts/im (ambas as formas) devolve 400 WrongContactType.

DELETE contacts/{id:guid} & contacts

Apaga um contacto pelo id, ou apaga em massa pelo filtro de contactos. Tal como nas tarefas, uma eliminação em massa com um filtro vazio é rejeitada com 400 EmptyFilter.

Códigos de confirmação

Os contactos não confirmados devem confirmar a sua propriedade com um código curto entregue no endereço do contacto.

• PATCH contacts/{id}/code — (re)emite e envia o código de confirmação. Devolve um ContactOperationResult com um status como CodeSent.
• POST contacts/{id}/code — confirma o contacto submetendo o código. Corpo: { "code": "12345" }. Em caso de sucesso, o contacto fica confirmado.

Alertas e subscrições

Uma subscrição associa uma ou mais tarefas e contactos a um conjunto de tipos de alerta e/ou relatório. Uma única entrada de subscrição faz o produto cruzado das suas tarefas e contactos, produzindo um alerta/relatório por cada combinação (tarefa, contacto, tipo).

Formato da subscrição

{
  "alertTypes": ["Up", "Down"],       // any of Up, Down, RepeatedlyDown
  "reportTypes": ["Day", "Month"],     // any of Day, Week, Month, Quarter, Year
  "taskIds": ["<task guid>"],
  "contactIds": ["<contact guid>"]
}

• É necessário pelo menos um de alertTypes / reportTypes, caso contrário AlertsAndReportsAreEmpty.
• Omitir taskIds assume por predefinição todas as suas tarefas; omitir contactIds assume por predefinição todos os seus contactos. Um array vazio explícito significa "nenhum".
• As subscrições de relatório aplicam-se apenas a contactos de Email — os tipos de relatório em contactos que não sejam de Email são ignorados silenciosamente (as respetivas subscrições de alerta continuam a ser criadas).
• Os ids que não lhe pertencem são ignorados.

GET subscriptions/alertTypes · subscriptions/reportTypes

GET subscriptions

Lista subscrições. Devolve uma entrada por cada subscrição de alerta ou relatório encontrada (nunca fundidas). Filtros opcionais:

POST subscriptions · DELETE subscriptions

Ambos aceitam um array JSON de entradas de subscrição no corpo. POST adiciona as subscrições descritas (só são inseridas linhas novas); DELETE remove as que existem. Ambos devolvem 200 OK com um corpo vazio. Tipos de alerta/relatório desconhecidos são rejeitados com UnknownAlertType / UnknownReportType.

[
  { "alertTypes": ["Up", "Down"],
    "taskIds": ["7ee87894-b8a9-e311-beb2-dc85de1f0bc2"],
    "contactIds": ["4cedf037-d1d9-e311-bebc-dc85de1f0bc2"] },
  { "reportTypes": ["Month"],
    "taskIds": ["7ee87894-b8a9-e311-beb2-dc85de1f0bc2"],
    "contactIds": ["4cedf037-d1d9-e311-bebc-dc85de1f0bc2"] }
]

curl -s -X POST https://api1.host-tracker.com/subscriptions \
  -H "Authorization: bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"alertTypes":["Up","Down"],"taskIds":["<task>"],"contactIds":["<contact>"]}]'

Estatísticas e resultados

GET stats

Agregados de tempo ativo/inativo por tarefa numa janela temporal. Aceita o filtro de tarefas para selecionar tarefas, mais:

Resposta

Um objeto Stats com a janela resolvida (campos de data duplos) e um array stats. Cada entrada transporta a referência da tarefa e: uptimeInMinutes/uptimeSpan, downtimeInMinutes/downtimeSpan, tempos de manutenção em cima/em baixo, totalTimeInMinutes, as contagens de verificações por intervalo, e uptimePercent/downtimePercent.

GET outages

Períodos de indisponibilidade por tarefa. Aceita o filtro de tarefas mais:

Resposta: um objeto Outages com a janela resolvida e um array taskOutages; cada elemento associa uma tarefa aos seus períodos de outages (startTime/endTime + variantes Unix, números de evento, comentário opcional).

GET incident

Lista de incidentes (eventos de falha) por tarefa. Aceita o filtro de tarefas mais os mesmos parâmetros de janela/fuso horário que outages, e:

Resposta: um objeto Incidents com um array taskIncidents. Cada incidente transporta taskId, checkId, tempos de início/fim em Unix, a location que falhou, o error, hasSnapshot, e (com fullLog) um bloco recheck a listar as localizações OK e as localizações em falha por erro.

GET incident/snapshot

Obtém o snapshot de resposta guardado para um incidente. Parâmetros:

Devolve o snapshot (um timestamp mais os bytes capturados) quando existe, ou null quando não há snapshot para o incidente indicado.

GET results/http

Métricas de tempo HTTP agregadas por tarefa. Força o tipo de tarefa Http. Aceita o filtro de tarefas mais:

Resposta: um objeto AggregatedHttpResults; cada entrada taskResults reporta a referência da tarefa e os valores médios de responseTime, dnsTime, headTime, dataTime (milissegundos).

GET cr/httpResponseTime

Série temporal do tempo de resposta HTTP por tarefa. Aceita o filtro de tarefas mais startDate, endDate e groupBy. Devolve um array simples de objetos de série:

[
  {
    "id": "ef10cd12-93f9-e311-bec5-dc85de1f0bc2",
    "rawUrl": "https://www.example.com",
    "name": "My website",
    "results": [ [1719181583, 142], [1719177983, 138] ]   // [unixSeconds, responseTimeMs], newest first
  }
]

Agentes

Os agentes são as localizações de monitorização geograficamente distribuídas. Os ids de pool devolvidos aqui são os valores que se passam no campo agentPools de uma tarefa.

GET agents

Lista os agentes de monitorização. Parâmetro de consulta opcional:

Cada agente transporta id, upFrom, datacenter (nome/cidade/país/estado), company (nome/url), ip, version, lon/lat, e pools.

[
  {
    "id": "a1b2c3d4-...-0001",
    "upFrom": "2024-06-20T08:00:00Z",
    "datacenter": { "name": "Example Hosting", "city": "Frankfurt", "country": "DE", "state": "" },
    "company": { "name": "Example Hosting", "url": "https://example-hosting.com" },
    "ip": "203.0.113.10",
    "version": "1.4.2",
    "lon": 8.68, "lat": 50.11,
    "pools": []
  }
]

GET agents/pools

Lista os pools de agentes públicos (regiões geográficas). Cada pool transporta id, desc, os seus agents, childPools, e hidden. Utilize os valores de id do pool no campo agentPools de uma tarefa.

GET agents/ips anónimo

Devolve os endereços IP atuais dos agentes de monitorização — útil para incluir o Host-Tracker numa lista branca de firewall. Este endpoint não exige autenticação. Por predefinição devolve text/plain, um IP por linha; envie Accept: application/json para receber um array JSON.

203.0.113.10
203.0.113.11
198.51.100.7

["203.0.113.10", "203.0.113.11", "198.51.100.7"]