CLI per URL shortener: accorciare i link dal terminale

Accorciare un URL dal terminale richiede una sola riga:

curl -s -X POST https://api.elido.app/v1/links \
  -H "Authorization: Bearer $ELIDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination_url":"https://example.com/spring-sale"}' | jq -r .short_url

Stampa https://s.elido.me/ab12cd e nient'altro. curl esegue la richiesta, jq estrae un campo dal JSON e -r rimuove le virgolette esterne, così il valore può essere passato direttamente agli appunti o a un altro comando.

Il resto di questo articolo presenta i quattro miglioramenti che trasformano quella riga in qualcosa che userai davvero: una funzione shell, codici di uscita affidabili, elaborazione bulk con concorrenza limitata e appunti. Se preferisci scriverlo in un linguaggio invece che nella shell, la stessa chiamata esiste in Python, Go e in altri sei runtime.

Trasformarlo in un comando

Un alias non può accettare un argomento, quindi usa una funzione. In .zshrc o .bashrc:

short() {
  [ -z "$1" ] && { echo "usage: short <url> [slug]" >&2; return 2; }

  local body
  body=$(jq -n --arg url "$1" --arg slug "${2:-}" \
    '{destination_url: $url} + (if $slug == "" then {} else {slug: $slug} end)')

  curl -s --fail-with-body -X POST https://api.elido.app/v1/links \
    -H "Authorization: Bearer $ELIDO_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(printf %s "$1" | shasum -a 256 | cut -d' ' -f1)" \
    -d "$body" | jq -r .short_url
}

Qui ci sono tre scelte deliberate.

Costruire il JSON con jq -n --arg invece di interpolare stringhe fa sì che una destinazione contenente una virgoletta o una e commerciale non interrompa la richiesta. È l'equivalente shell dell'SQL parametrizzato, e saltare questo passaggio produce la stessa classe di bug.

--fail-with-body è il flag che molti dimenticano. Per impostazione predefinita curl termina con codice 0 per qualsiasi scambio completato, quindi un 401 passa attraverso la pipe, jq stampa null e lo script continua con null al posto dello short link. Con questo flag, un 4xx imposta uno stato di uscita diverso da zero e puoi comunque leggere il corpo dell'errore.

La Idempotency-Key derivata dall'URL fa sì che eseguire due volte lo stesso comando restituisca lo stesso link invece di crearne due. Questo conta ancora di più nella sezione sull'elaborazione bulk qui sotto, e il ragionamento è spiegato in limiti di frequenza e idempotenza.

Ti serve una chiave? Creane una con il piano gratuito, esportala dal profilo della shell e la funzione funzionerà nel prossimo terminale.

Direttamente negli appunti

Gli ultimi caratteri che fanno sembrare il flusso davvero completo:

short "https://example.com/spring-sale" | tee /dev/tty | pbcopy      # macOS
short "https://example.com/spring-sale" | tee /dev/tty | xclip -sel c # Linux, X11
short "https://example.com/spring-sale" | tee /dev/tty | wl-copy     # Wayland
short "https://example.com/spring-sale" | tee /dev/tty | clip.exe    # WSL

tee /dev/tty stampa il link e lo copia nello stesso momento, il che è meglio che copiare alla cieca e sperare.

Elaborazione bulk senza accumulare 429

Un file di URL, accorciati otto alla volta:

export -f short                      # bash; zsh users call the script directly
xargs -P 8 -I{} bash -c 'short "{}"' < urls.txt > short-urls.txt

-P 8 è l'intera strategia per il limite di frequenza: otto richieste in corso indipendentemente dal fatto che il file contenga cinquanta righe o cinquantamila. Senza questo parametro, xargs le esegue alla massima velocità con cui riesce ad avviare processi e l'API risponde con 429 alla maggior parte.

Ci sono due precisazioni da conoscere prima di applicarlo a un file reale. xargs -P mescola l'output, quindi le righe possono arrivare fuori ordine; se la corrispondenza tra input e output è importante, stampa entrambi:

xargs -P 8 -I{} bash -c 'printf "%s\t%s\n" "{}" "$(short "{}")"' < urls.txt > mapping.tsv

Inoltre, un URL contenente uno spazio o una virgoletta non sopravvive a -I{} senza escaping. Per qualsiasi dato fornito dall'utente, xargs -0 con un file di input delimitato da caratteri nulli è la versione sicura. A quel punto, uno script vero in Python richiede di solito meno lavoro che gestire correttamente le virgolette.

Tenere la chiave fuori dalla cronologia

ELIDO_API_KEY=abc123 short <url> inserisce la chiave in ~/.zsh_history e nell'elenco dei processi, dove qualsiasi altro account sulla macchina può leggerla con ps.

Esportala invece dal profilo della shell oppure, meglio ancora, recuperala da un archivio di segreti all'avvio della shell:

export ELIDO_API_KEY="$(security find-generic-password -s elido -w)"      # macOS Keychain
export ELIDO_API_KEY="$(pass show elido/api-key)"                          # pass

Ruotare una chiave significa così aggiornare una sola voce invece di cercare nei dotfile di tre macchine. Lo stesso principio vale sul lato server di qualsiasi script pianificato, mentre i webhook per gli eventi dei link sono il modello per recuperare dati senza lasciare un'altra chiave da qualche parte.

Quando il terminale è il posto giusto

È il posto giusto quando gli URL sono già in un file, quando ti trovi già in una shell o quando l'accorciamento è un passaggio di uno script più ampio: un processo di rilascio che genera un link di distribuzione, un job CI che accorcia l'URL di un deployment di anteprima, un hook git che produce un link per una voce del changelog.

È il posto sbagliato per gestire una campagna. Cartelle, tag e confronto del volume di clic tra diversi posizionamenti richiedono una dashboard, e cercare di farlo con query jq contro un endpoint che restituisce un elenco è un progetto, non una scorciatoia. Soluzioni per sviluppatori spiega cosa espone l'API oltre alla creazione, mentre l'API e gli SDK descrive i client tipizzati da usare quando uno script shell non basta più.

Leggi la serie principale

Questo articolo appartiene al cluster engineering. Inizia dalla guida gratuita all'API per URL shortener per la struttura dell'endpoint, poi passa a limiti di frequenza e idempotenza. Il riferimento aggiornato è la documentazione dell'API.

Articoli correlati sul blog

• Come accorciare un URL in Python con la libreria requests
• Come accorciare un URL in PowerShell con Invoke-RestMethod
• Come vedere dove porta un URL breve prima di fare clic
• Short link come Terraform: gestione dichiarativa dei link