Połączenie z REST API NowMetrix

Po zalogowaniu do NowMetrix należy przejść do Ustawienia → API i utworzyć klucz API z etykietą opisującą integrację, na przykład Panel wewnętrzny lub Google Sheets. Można mieć maksymalnie 10 aktywnych kluczy. Nowy lub obrócony klucz należy skopiować od razu — jego pełna wartość jest wyświetlana tylko raz.

NOWMETRIX_API_KEY=nm_YOUR_KEY

Zmiana nazwy klucza nie zmienia jego wartości. Rotacja lub unieważnienie jednego klucza wpływa wyłącznie na ten klucz. Wszystkie klucze korzystają z uprawnień przypisanych użytkownikowi NowMetrix i współdzielą limit żądań danego trackera.

REST API jest bezstanowe: nie ma osobnego żądania logowania ani trwałej sesji. Przy każdym żądaniu HTTPS należy wysyłać klucz API jako token Bearer.

GET https://api.nowmetrix.com/api/me
Authorization: Bearer nm_YOUR_KEY
Accept: application/json

• Podstawowy adres URL: https://api.nowmetrix.com
• Uwierzytelnianie: Authorization: Bearer nm_YOUR_KEY
• Test połączenia: GET /api/me nie wymaga parametru trackera.
• Limity czasu: w każdym kliencie należy ustawić skończony limit czasu połączenia i oczekiwania na odpowiedź.

Najszybszym sposobem sprawdzenia połączenia z poziomu terminala jest użycie cURL.

API_KEY="nm_YOUR_KEY"

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "Accept: application/json" \
  "https://api.nowmetrix.com/api/me"

Pomyślne żądanie zwraca kod HTTP 200 oraz listę trackerów dostępnych dla klucza API:

{
  "authenticated": true,
  "current_tracker": "TRACKER_ID",
  "trackers": [
    {
      "tracker": "TRACKER_ID",
      "host": "example-media.test"
    },
    {
      "tracker": "SECOND_TRACKER_ID",
      "host": "example-studio.test"
    }
  ]
}

Należy korzystać z rozszerzenia cURL dla PHP i przechowywać klucz API w zmiennej środowiskowej.

<?php

$apiKey = getenv('NOWMETRIX_API_KEY');
if (!is_string($apiKey) || $apiKey === '') {
    throw new RuntimeException('NOWMETRIX_API_KEY is not set.');
}

$curl = curl_init('https://api.nowmetrix.com/api/me');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT => 10,
]);

$body = curl_exec($curl);
if ($body === false) {
    $error = curl_error($curl);
    curl_close($curl);
    throw new RuntimeException($error);
}

$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status < 200 || $status >= 300) {
    throw new RuntimeException("NowMetrix API returned HTTP {$status}: {$body}");
}

$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($data);

Po stronie serwera można korzystać z wbudowanego API fetch. Klucza API nie należy ujawniać w kodzie JavaScript uruchamianym w przeglądarce.

const apiKey = process.env.NOWMETRIX_API_KEY;
if (!apiKey) throw new Error('NOWMETRIX_API_KEY is not set.');

async function main() {
  const response = await fetch('https://api.nowmetrix.com/api/me', {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: 'application/json',
    },
    signal: AbortSignal.timeout(10_000),
  });

  const body = await response.text();
  if (!response.ok) {
    throw new Error(`NowMetrix API returned HTTP ${response.status}: ${body}`);
  }

  console.log(JSON.parse(body));
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Pakiet requests zapewnia zwięzłego klienta z jawnym ustawieniem limitu czasu i obsługą statusu. Instalacja wymaga wykonania polecenia python -m pip install requests.

import os
import requests

api_key = os.environ["NOWMETRIX_API_KEY"]
response = requests.get(
    "https://api.nowmetrix.com/api/me",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Accept": "application/json",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

Standardowy HttpClient języka Java wystarcza do wykonania uwierzytelnionego żądania.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class NowMetrixExample {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("NOWMETRIX_API_KEY");
        if (apiKey == null || apiKey.isBlank()) {
            throw new IllegalStateException("NOWMETRIX_API_KEY is not set.");
        }

        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.nowmetrix.com/api/me"))
            .timeout(Duration.ofSeconds(10))
            .header("Authorization", "Bearer " + apiKey)
            .header("Accept", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = client.send(
            request, HttpResponse.BodyHandlers.ofString()
        );
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            throw new IllegalStateException(
                "NowMetrix API returned HTTP " + response.statusCode() + ": " + response.body()
            );
        }

        System.out.println(response.body());
    }
}

Do żądania można użyć HttpClient z nagłówkiem autoryzacji Bearer i limitem czasu ustawionym na poziomie aplikacji.

using System.Net.Http.Headers;

var apiKey = Environment.GetEnvironmentVariable("NOWMETRIX_API_KEY")
    ?? throw new InvalidOperationException("NOWMETRIX_API_KEY is not set.");

using var client = new HttpClient
{
    BaseAddress = new Uri("https://api.nowmetrix.com"),
    Timeout = TimeSpan.FromSeconds(10),
};
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", apiKey);
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json")
);

using var response = await client.GetAsync("/api/me");
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"NowMetrix API returned HTTP {(int)response.StatusCode}: {body}"
    );
}
Console.WriteLine(body);

Standardowy klient net/http umożliwia pobranie odpowiedzi JSON do ogólnej struktury lub własnych typów danych.

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

func main() {
	apiKey := os.Getenv("NOWMETRIX_API_KEY")
	if apiKey == "" {
		panic("NOWMETRIX_API_KEY is not set")
	}

	request, err := http.NewRequest(http.MethodGet, "https://api.nowmetrix.com/api/me", nil)
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer "+apiKey)
	request.Header.Set("Accept", "application/json")

	client := &http.Client{Timeout: 10 * time.Second}
	response, err := client.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()

	if response.StatusCode < 200 || response.StatusCode >= 300 {
		panic("NowMetrix API returned " + response.Status)
	}

	var data map[string]any
	if err := json.NewDecoder(response.Body).Decode(&data); err != nil {
		panic(err)
	}
	fmt.Printf("%#v\n", data)
}

Standardowa biblioteka Ruby umożliwia wykonanie żądania bez dodatkowego pakietu HTTP.

require 'json'
require 'net/http'

api_key = ENV.fetch('NOWMETRIX_API_KEY')
uri = URI('https://api.nowmetrix.com/api/me')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{api_key}"
request['Accept'] = 'application/json'

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true,
  open_timeout: 10,
  read_timeout: 10
) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "NowMetrix API returned HTTP #{response.code}: #{response.body}"
end

puts JSON.pretty_generate(JSON.parse(response.body))

Przed zdekodowaniem danych z pomyślnej odpowiedzi należy sprawdzić status HTTP. Odpowiedzi z błędami mają ustaloną strukturę JSON z przeznaczonym dla maszyn polem error.code.

• 401 missing_token: brakuje nagłówka Authorization.
• 401 invalid_token: klucz jest nieprawidłowy, unieważniony lub zastąpiony.
• 403 site_not_authorized: klucz nie ma dostępu do żądanego trackera.
• 429 rate_limit_exceeded: przed ponowieniem żądania należy odczekać przez czas określony w Retry-After.
• 503: w przypadku tymczasowych awarii backendu należy ponawiać próby z ograniczonym wykładniczym wydłużaniem odstępów między nimi.

{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}

Należy odczytać wartość current_tracker lub trackers[].tracker z /api/me, a następnie przekazać identyfikator trackera jako parametr zapytania site.

GET https://api.nowmetrix.com/v1/realtime?site=TRACKER_ID
Authorization: Bearer nm_YOUR_KEY
Accept: application/json