Skip to content

staleTtl
PRO

Type:
<string> | <number> | <boolean>

Default: false
It enables serve a stale response while a background refresh cache copy is being generated over the target url.

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://microlink.io' URL with 'ttl' & 'staleTtl' API parameters:

CLI Microlink API example

microlink https://microlink.io&ttl=1d&staleTtl=0

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://microlink.io" \
  -d "ttl=1d" \
  -d "staleTtl=0"

JavaScript Microlink API example

import createClient from 'microlink.io'

const microlink = createClient()

const data = await microlink.metadata('https://microlink.io', {
  ttl: "1d",
  staleTtl: 0
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://microlink.io",
    "ttl": "1d",
    "staleTtl": "0"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://microlink.io",
  ttl: "1d",
  staleTtl: "0"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://microlink.io",
    "ttl" => "1d",
    "staleTtl" => "0"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://microlink.io")
    q.Set("ttl", "1d")
    q.Set("staleTtl", "0")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}
The value provided can't be higher than ttl, being supported the following formats:
  • as number in milliseconds (e.g., 86400000).
  • as humanized representation of the number (e.g., '24h').
false turns it off, which is the default. true, an empty staleTtl, or any value that is not one of these formats is rejected with EINVALQUERY.
The following humanized number variations are supported:
https://microlink.io&staleTtl=1d        # 86400000
https://microlink.io&staleTtl=1day      # 86400000
https://microlink.io&staleTtl=1days     # 86400000

https://microlink.io&staleTtl=1h        # 3600000
https://microlink.io&staleTtl=1hour     # 3600000
https://microlink.io&staleTtl=1hours    # 3600000

https://microlink.io&staleTtl=90s       # 90000
https://microlink.io&staleTtl=90secs    # 90000
https://microlink.io&staleTtl=90second  # 90000
https://microlink.io&staleTtl=90seconds # 90000
A good pattern is to set staleTtl=0 to always revalidate in the background under expiration, maximizing the cache usage serving the last cache copy generated while the revalidation will refresh it.