URL-verkorter-CLI: links verkorten vanuit de terminal

Een URL verkorten vanuit de terminal is één regel:

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

Die print https://s.elido.me/ab12cd en verder niets. curl doet het verzoek, jq haalt één veld uit de JSON en -r laat de omringende aanhalingstekens weg, zodat de waarde rechtstreeks naar een klembord of een ander commando kan.

De rest van dit artikel bestaat uit de vier verbeteringen die van die regel iets maken wat je echt gebruikt: een shellfunctie, eerlijke afsluitcodes, bulk met begrensde gelijktijdigheid en het klembord. Schrijf je het liever in een programmeertaal dan in shell, dan bestaat dezelfde aanroep in Python, Go en zes andere runtimes.

Maak er een commando van

Een alias kan geen argument aannemen, dus gebruik een functie. In .zshrc of .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
}

Drie bewuste keuzes daarin.

De JSON bouwen met jq -n --arg in plaats van stringinterpolatie betekent dat een bestemming met een aanhalingsteken of een ampersand het verzoek niet breekt. Dit is het shell-equivalent van geparametriseerde SQL, en het overslaan ervan is dezelfde soort bug.

--fail-with-body is de vlag die mensen missen. Standaard sluit curl af met 0 bij elke voltooide uitwisseling, dus een 401 stroomt door de pipe, jq print null en een script gaat verder met null op de plek van een link. Met de vlag zet een 4xx een afsluitstatus ongelijk aan nul en krijg je nog steeds de foutbody om te lezen.

De Idempotency-Key die van de URL is afgeleid, betekent dat hetzelfde commando twee keer uitvoeren dezelfde link teruggeeft in plaats van er twee aan te maken. Dat is belangrijker in het bulkonderdeel hieronder, en de redenering staat in rate limits en idempotentie.

Een sleutel nodig? Maak er een aan in het gratis abonnement, exporteer hem vanuit je shellprofiel en de functie werkt in de eerstvolgende nieuwe terminal.

Rechtstreeks naar het klembord

De laatste paar tekens waardoor het af voelt:

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 print de link en kopieert hem in één adem, en dat is beter dan blind kopiëren en hopen.

Bulk zonder 429's te verzamelen

Een bestand met URL's, één per regel, acht tegelijk verkort:

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

-P 8 is de hele rate-limitstrategie: acht verzoeken tegelijk onderweg, of het bestand nu vijftig regels telt of vijftigduizend. Zonder die vlag voert xargs ze uit zo snel als het processen kan starten en antwoordt de API op de meeste met 429.

Twee kanttekeningen om te kennen voordat je dit op een echt bestand richt. xargs -P mengt de uitvoer door elkaar, dus regels kunnen in een andere volgorde binnenkomen; als de koppeling tussen invoer en uitvoer ertoe doet, print dan beide:

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

En een URL met een spatie of een aanhalingsteken overleeft -I{} niet zonder escaping. Voor alles wat door gebruikers is aangeleverd is xargs -0 met een invoerbestand dat met nulbytes is gescheiden de veilige versie. Op dat punt is een echt script in Python meestal minder werk dan de quoting goed krijgen.

Houd de sleutel uit je geschiedenis

ELIDO_API_KEY=abc123 short <url> zet de sleutel in ~/.zsh_history en in de processenlijst, waar elk ander account op de machine hem met ps kan lezen.

Exporteer hem in plaats daarvan vanuit je shellprofiel, of haal hem beter bij het starten van de shell uit een geheimenopslag:

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

Een sleutel roteren betekent dan één item bijwerken in plaats van dotfiles op drie machines doorzoeken. Hetzelfde principe geldt aan de serverkant van elk script dat je inplant, en webhooks voor linkgebeurtenissen is het patroon om data terug te krijgen zonder dat er nog een sleutel ergens anders staat.

Wanneer de terminal de juiste plek is

Het is de juiste plek als de URL's al in een bestand staan, als je toch al in een shell zit of als het verkorten één stap is van een groter script: een releaseproces dat een downloadlink genereert, een CI-job die de URL van een previewdeployment verkort, een git-hook die een link maakt voor een changelogregel.

Het is de verkeerde plek om een campagne te beheren. Mappen, tags en klikvolumes vergelijken tussen plaatsingen vragen om een dashboard, en dat proberen met jq-queries tegen een lijst-endpoint is een project en geen snelkoppeling. Oplossingen voor ontwikkelaars behandelt wat de API naast aanmaken nog aanbiedt, en de API en SDK's behandelt de getypeerde clients voor als een shellscript niet meer volstaat.

Lees de cornerstone-reeks

Dit hoort bij het engineeringcluster. Begin met de gids voor een gratis URL-verkorter-API voor de vorm van het endpoint, en lees daarna rate limits en idempotentie. De actuele referentie is de API-documentatie.

Gerelateerd op de blog

• Een URL verkorten in Python met de requests-bibliotheek
• Zien waar een korte URL heen gaat voordat je klikt
• Korte links als Terraform: declaratief linkbeheer