FAQ

Domande frequenti su IPFS Ninja.

Generale

Cos'e' IPFS Ninja?

IPFS Ninja e' un servizio gestito di pinning IPFS. Carichi qualsiasi file tramite una semplice API REST, oppure pinni CID esistenti dalla rete IPFS. Ogni file riceve un identificatore di contenuto permanente (CID) ed e' accessibile tramite il nostro gateway su ipfs.ninja/ipfs/<CID>.

Quali tipi di file sono supportati?

Tutti i tipi di file sono supportati. Oggetti e array JSON possono essere inviati direttamente. Tutti gli altri file (immagini, PDF, HTML, video, audio, binari) vengono inviati come contenuto codificato in base64.

C'e' un limite di dimensione del file?

I singoli upload sono limitati dall'allocazione di spazio del tuo piano. Non c'e' un limite di dimensione per singolo file oltre lo spazio disponibile.

Posso pinnare contenuti gia' esistenti su IPFS?

Si'. Usa POST /pin con qualsiasi CID valido. Il nostro cluster recuperera' il contenuto dalla rete IPFS e lo pinnera' al tuo account. Consulta la documentazione dell'API Pinning per i dettagli.

Quanto tempo richiede il pinning?

Dipende dalla dimensione del file e da quanti nodi IPFS hanno il contenuto. File piccoli e ben distribuiti vengono pinnati in pochi secondi. Contenuti grandi o raramente pinnati possono richiedere alcuni minuti. L'endpoint di pin risponde immediatamente con stato pinning — interroga GET /pin/:cid per verificare l'avanzamento.

Cosa succede se un CID non viene trovato?

Lo stato diventa failed. Cio' significa che il CID e' invalido oppure il contenuto non e' piu' disponibile su nessun nodo IPFS raggiungibile.

I dati caricati su IPFS sono pubblici?

Si'. Tutto il contenuto pinnato su IPFS e' pubblicamente accessibile tramite il suo CID attraverso qualsiasi gateway IPFS. Se hai bisogno di accesso privato, usa un gateway dedicato con modalita' token-required — questo limita l'accesso attraverso il tuo gateway, anche se il contenuto rimane disponibile sulla rete IPFS piu' ampia.

I miei file rimarranno su IPFS se cancello il mio account?

Rimuoviamo il pin dei tuoi file dai nostri nodi quando cancelli. Se altri nodi IPFS hanno memorizzato nella cache il tuo contenuto, potrebbe rimanere accessibile. Tuttavia, senza pinning attivo, i file verranno eventualmente rimossi dalla garbage collection attraverso la rete.

Autenticazione e API

Come autentico le richieste API?

Passa la tua API key tramite l'header X-Api-Key. Genera le chiavi dalla pagina API Keys nella tua dashboard.

Ci sono limiti di frequenza sulle API?

No. IPFS Ninja non impone limiti di frequenza sulle richieste API. Puoi fare tutte le richieste necessarie con qualsiasi piano.

Le API key scadono?

No. Le API key sono valide finche' non le elimini. Puoi creare piu' chiavi e revocarle singolarmente.

Qual e' la differenza tra API key e token gateway?

Le API key (bws_) hanno accesso completo — caricamento, eliminazione, elenco file. I token gateway (gwt_) sono in sola lettura e possono accedere ai file solo tramite il tuo gateway dedicato. I token gateway sono sicuri da incorporare nelle app frontend.

Gateway dedicati

Cos'e' un gateway dedicato?

Un gateway IPFS privato sul tuo sottodominio (es. abc123.gw.ipfs.ninja) che serve solo i file pinnati al tuo account. A differenza del gateway pubblico, non risolvera' CID di altri utenti.

Quali piani includono un gateway dedicato?

I gateway dedicati sono disponibili nel piano Nirvana ($29/mese), che include 50 GB/mese di larghezza di banda gateway.

Posso limitare chi accede al mio gateway?

Si'. Puoi abilitare la modalita' token-required (richiede un token gwt_ per ogni richiesta) e/o impostare una whitelist IP (fino a 100 indirizzi).

Posso limitare il mio gateway per origine/dominio?

Si'. Configura allowedOrigins nelle impostazioni del gateway con un elenco di origini HTTPS. Solo le richieste del browser provenienti da quelle origini saranno consentite. Le richieste non-browser (senza header Origin) passano senza restrizioni. Un elenco vuoto consente tutte le origini.

Cosa sono i token di caricamento firmati?

I token di caricamento firmati sono credenziali a tempo limitato per caricamenti lato client. Li generi sul tuo server usando POST /upload/signed-url e li passi ai browser o app mobile. Il client si autentica con Authorization: Signed <token> invece di esporre la tua API key. Ogni token traccia l'utilizzo e scade automaticamente. Consulta la documentazione sui Token firmati per i dettagli.

Posso ottimizzare le immagini servite da IPFS?

Si'. Usa GET /image/:cid con parametri di query come w, h, format e quality per ridimensionare, convertire e comprimere le immagini al volo. Le risposte vengono memorizzate nella cache in base al CID. Funziona su tutti i piani. Vedi Ottimizzazione immagini.

Posso allegare metadati ai file?

Si'. Includi un oggetto metadata con fino a 10 coppie chiave-valore durante il caricamento tramite POST /upload/new o il pinning tramite POST /pin. I metadati vengono restituiti nell'elenco dei file e nell'endpoint di dettaglio del file. Consulta la documentazione su File e Pinning.

Fatturazione e piani

C'e' un piano gratuito?

Si'. Il piano Dharma e' gratuito per sempre — 1 GB di spazio di archiviazione, richieste API illimitate, nessuna carta di credito richiesta.

Ci sono costi di larghezza di banda?

Nessun costo di larghezza di banda sulle richieste API per qualsiasi piano. La larghezza di banda del gateway dedicato (piano Nirvana) include 50 GB/mese. Quando il limite viene raggiunto, le richieste gateway vengono bloccate fino al mese successivo.

Lo spazio di archiviazione si azzera?

Lo spazio di archiviazione non si azzera. Il tuo piano include un'allocazione totale di archiviazione (1 GB / 10 GB / 100 GB). Per liberare spazio, elimina i file che non ti servono piu'. L'upgrade del piano aumenta la tua allocazione totale.

Posso cancellare in qualsiasi momento?

Si'. Cancella il tuo abbonamento tramite il portale di fatturazione — senza vincoli. Il tuo account torna al livello gratuito e i file pinnati esistenti rimangono accessibili.

Cosa succede ai miei file se faccio il downgrade?

I tuoi file rimangono pinnati su IPFS, ma non puoi caricare altro se il tuo utilizzo attuale supera il limite di archiviazione del nuovo piano. Elimina file per tornare sotto il limite.

Sicurezza

I miei dati sono crittografati?

Tutti i dati sono crittografati in transito tramite TLS/HTTPS. L'autenticazione usa token JWT (Cognito) e API key archiviate in modo sicuro. Il contenuto dei file su IPFS non e' crittografato a riposo — IPFS e' una rete pubblica per progettazione.

E' sicuro usare le API key nel mio codice lato server?

Si'. Le API key sono progettate per l'uso lato server. Non esporle mai nel codice lato client. Per l'accesso ai file lato client, usa i token gateway (gwt_) che sono in sola lettura.

Supporto

Come posso ottenere aiuto?

Invia un'email a info@ipfs.ninja o consulta la documentazione del Riferimento API.

C'e' un SLA?

Ci impegniamo per un'alta disponibilita' ma al momento non offriamo un SLA formale. Il servizio e' fornito "cosi' com'e'".