Noțiuni introductive

Conectează-te la serviciile MediaShare prin REST, MCP sau skill-uri pentru agenți.

1. Trei modalități de conectare

MediaShare urmează principiul API-first. Fiecare serviciu este un API HTTP independent, completat de un server MCP și documentat printr-un skill pentru agenți.

Alege metoda de integrare potrivită arhitecturii tale:

Modalități de integrare MediaShare

Direct HTTP API  ──> Pentru microservicii, scripturi și aplicații
MCP Server       ──> Pentru platforme cu agenți AI (Claude Desktop, Cursor, Pi, Codex)
Agent Skill      ──> Pentru fluxuri de lucru și instrucțiuni procedurale

2. Prima cerere HTTP

Serviciile cu acces public, precum geolocalizarea IP, pot fi apelate fără autentificare. Serviciile protejate necesită un token Bearer în antetul Authorization.

Exemple cURL

# Public lookup example
curl -X GET "https://geo.mediashare.ro/" \
  -H "Accept: application/json"

# Authenticated service example
curl -G "https://wine.mediashare.ro/api/wine/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "q=Purcari Malbec 2020"

Arhitectură și principii

Deciziile de arhitectură și constrângerile operaționale ale serviciilor MediaShare.

Servicii independente

Fiecare subdomeniu (de exemplu wine.mediashare.ro și geo.mediashare.ro) este un serviciu distinct, cu propriul mediu de execuție, monitorizare și ritm de lansare.

Traficul nu trece printr-un gateway API monolitic; fiecare serviciu evoluează independent.

OpenAPI 3.1 este contractul canonic

Contractul HTTP este sursa canonică. Serverele MCP și skill-urile traduc și documentează utilizarea fără să dubleze logica de business.

Specificațiile OpenAPI sunt publicate la /openapi.json pe domeniul fiecărui serviciu.

Determinist și ușor de întreținut

Preferăm transformări deterministe, actualizări programate și răspunsuri cu cache în locul proceselor editoriale care necesită curare manuală.

Autentificare și cote

Chei API, antete și limite de trafic.

Autentificare cu cheie API

Trimite cheia API ca token Bearer în antetul HTTP Authorization.

Nu include niciodată cheile API în controlul versiunilor și nu le expune în aplicații front-end.

Antet de autentificare

GET /v1/extract HTTP/1.1
Host: meta.mediashare.ro
Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxx
Accept: application/json

Antete standard de răspuns

Răspunsurile API includ metadate standard pentru urmărirea cererilor și limitarea traficului:

Urmărire și limite de trafic

X-Request-Id:          Unique UUID for distributed request tracing
RateLimit-Limit:       Maximum allowed requests in the current window
RateLimit-Remaining:   Number of available requests remaining
RateLimit-Reset:       Unix timestamp when the rate limit window resets

Securitate și protecție SSRF

Protecții, limite pentru descărcarea datelor și politici de confidențialitate.

Protecție SSRF

Serviciile care accesează adrese URL externe validează schema și gazda înainte și după rezolvarea DNS, blochează adresele private și limitează timpul și dimensiunea răspunsului.

Confidențialitatea datelor și jurnalizare minimă

Serviciile MediaShare înregistrează doar telemetrie operațională, precum identificatorul cererii, codul HTTP, latența și tipul erorii. În mod implicit, datele trimise de utilizatori și conținutul extras nu sunt păstrate.

Specificații Canonice OpenAPI

Fiecare serviciu își publică independent contractul OpenAPI 3.1 la adresa /openapi.json.

Service	Domain	Status	OpenAPI 3.1 Contract
wine	`wine.mediashare.ro`	ACTIV	`https://wine.mediashare.ro/openapi/direct.json`
geo	`geo.mediashare.ro`	ACTIV	`https://geo.mediashare.ro/openapi.json`
ro-finance	`ro-finance.mediashare.ro`	ACTIV	`https://ro-finance.mediashare.ro/openapi.json`
meta	`meta.mediashare.ro`	ÎN DEZVOLTARE	In Design
mock	`mock.mediashare.ro`	PLANIFICAT	In Design
seo	`seo.mediashare.ro`	PLANIFICAT	In Design

Documentație