Introduzione alle API

Urly mette a disposizione delle semplici API per permettere agli sviluppatori di integrare le proprie applicazioni con i servizi di Urly. L'uso delle API è riservato agli iscritti a Urly Plus.

Ottenere una chiave

Dopo aver effettuato l'accesso con un account Urly Plus, visitare la pagina Chiavi API. Digitare un nome per identificare la chiave che si sta generando, in modo da riconoscerla facilmente in seguito, e fare clic su Genera chiave.

Per motivi di sicurezza, la chiave appena generata sarà visualizzata una sola volta. Copiarla e salvarla in un luogo sicuro.

Revocare una chiave

Le chiavi generate possono essere revocate in qualsiasi momento. Revocando una chiave, l'integrazione di qualsiasi applicazione che sta usando questa chiave smetterà di funzionare.

Limitazioni

Per prevenire abusi, le API sono limitate alla generazione di 1000 link al mese. In caso siano necessarie quote maggiori, contattaci.

Autenticazione

Utilizzare la chiave API per autenticare ogni richiesta. L’autenticazione avviene tramite un header HTTP Authorization, dove {token} andrà sostituito con la chiave generata, come nel seguente esempio:

Authorization: Bearer {token}

Formato richieste e risposta

Tutte le chiamate alle API di Urly e le relative risposte sono codificate in formato application/json.

Il codice di stato HTTP indica il tipo di risposta:

• 200 OK per una chiamata completata con successo;
• 401 Unauthorized in caso di chiave errata o revocata;
• 402 Payment Required nel caso in cui non si abbia un account Urly Plus attivo;
• 403 Forbidden in caso non si abbiano i permessi per effettuare una richiesta;
• 404 Not Found in caso si stia cercando di accedere a una risorsa o a un endpoint non esistente;
• 422 Unprocessable Content in caso vi sia un errore di validazione;
• 429 Too Many Requests in caso siano stati superati i limiti mensili;
• 500 Server Error in caso di un errore interno del server.

Errori di validazione

Gli errori di validazione sono restituiti con lo stato HTTP 422 Unprocessable Content. La loro risposta segue il seguente formato:

{
  "message": "The given data was invalid.",
  "errors": {
    "destination": [
      "Il campo destination è obbligatorio."
    ]
  }
}

errors è un oggetto le cui chiavi sono i nomi dei campi che presentano errori di validazione. Ad ogni chiave corrisponde un array con la lista di errori in formato leggibile.