Skip to content

api-reference.md

Latest commit

 

History

History
108 lines (81 loc) · 5.1 KB

api-reference.md

File metadata and controls

108 lines (81 loc) · 5.1 KB
Raw

API reference — compress-php

⛔ Niente di quanto segue è implementato oggi. Questo documento descrive la superficie pubblica attesa del SDK PHP, derivata metodo per metodo dall'interfaccia ICompress di compress-go. Serve come specifica del porting: ogni firma qui elencata va spuntata nella matrice di status.md quando viene implementata e coperta da test.

Namespace di destinazione proposto: HiWay\Compress (quello attuale, Compress-php\Compress, non è PHP valido).

Costruzione

use HiWay\Compress\Compress;

$compress = new Compress(
    customerName: getenv('COMPRESS_CUSTOMER_NAME'),
    apiKey:       getenv('COMPRESS_API_KEY'),
    debug:        false,
);
Parametro Tipo Note
customerName string obbligatorio; da qui deriva client_id = <customerName>_client (invariato se finisce già in _client)
apiKey string obbligatorio
debug bool log delle richieste; non deve mai stampare credenziali

Il costruttore chiama /external/credentials/ e memorizza customer_id: con credenziali errate fallisce subito con un'eccezione.

Diagnostica

Metodo Ritorno Endpoint
healthCheck(): void eccezione se l'API non risponde /health
isDebug(): bool — locale

Credenziali e cliente

Metodo Ritorno Endpoint
getCredentials(): Credential credenziali complete del cliente (S3, SFTP, base URL VOD/live) /external/credentials/
getCustomerS3Zone(): CustomerS3 zona e bucket di upload — da chiamare prima di un upload /external/customers/s3

Categorie

Metodo Ritorno Endpoint
getCategories(): Category[] elenco categorie /external/upload/categories
createCategory(string $name): Category categoria creata …/categories/create

Upload / VOD

Metodo Ritorno Endpoint
getUploads(UploadsPaginated $p): VideoUploadInfo[] elenco upload /external/upload
getSingleUpload(int $jobId): VideoUploadInfo dettaglio job …/upload/jobid
getJobidProgress(int $jobId): VideoUploadInfo avanzamento encoding …/upload/job_progress/jobid
setPublishedUpload(int $jobId, int $published): VideoUploadInfo pubblica/spubblica …/upload/set_published
upload(string $file, string $filename, int $size, int $categoryId, string $title, string $tags, string $location): ResponseUpload flusso a 3 passi (zone → presigned → PUT S3 → create) vedi sotto

Esempio del flusso completo:

$s3   = $compress->getCustomerS3Zone();          // zone + bucket_upload
$info = $compress->upload(
    file:       file_get_contents('/path/video.mp4'),
    filename:   'video.mp4',
    size:       filesize('/path/video.mp4'),
    categoryId: 12,
    title:      'Titolo',
    tags:       'tag1,tag2',
    location:   'Milano',
);
// poi si segue il job:
$progress = $compress->getJobidProgress($info->jobId);

Il file non transita dall'API: viene messo con un PUT sull'URL pre-firmato restituito da …/upload/presignedUrl. Dettaglio in architecture.md.

Restreamer (live)

Metodo Ritorno Endpoint
getRestreamers(int $startFrom, int $amount): Restreamer[] elenco paginato /external/restreamers
getRestreamersOttAll(int $startFrom, int $amount): RestreamersOTTResponse vista OTT …/restreamers/ott_all
getSingleRestreamer(string $instanceName): Restreamer dettaglio istanza …/restreamers/single_instance
scaleRestreamer(string $instanceName, int $scale): ResponseServer scala l'istanza …/restreamers/scale_instance
restreamerHlsStart(string $instanceName, string $streamProtocol): HlsResponse avvia HLS …/restreamers/hls/start
restreamerHlsStop(string $instanceName, string $streamProtocol): HlsResponse ferma HLS …/restreamers/hls/stop

Le varianti push/* e pull/* presenti nelle costanti PHP non hanno controparte nel SDK Go: non implementarle finché la firma non è confermata (vedi endpoints.md).

Eventi

Metodo Ritorno Endpoint
createEventsBulk(InstancesEventCreate[] $request): ResponseServer creazione massiva /external/events/create_bulk
restreamerEventsHistory(int $startFrom, int $amount): RestreamerEvent[] storico eventi /external/events/history
generateVodProxy(string $eventId, string $instanceName, string $title): GenerateVodResponse live → VOD /external/events/generate_vod

Errori

Tutti i metodi devono lanciare — mai restituire null in silenzio:

Eccezione proposta Quando
InvalidArgumentException customerName / apiKey vuoti, parametri obbligatori mancanti
CompressApiException l'API risponde {"response": "KO", "message": "…"} (anche con HTTP 200)
CompressTransportException errore HTTP/rete (Guzzle), timeout, risposta non-JSON

Il caso response == "KO" con HTTP 200 è la trappola principale: un client che guarda solo lo status code considera riuscite chiamate fallite.