HTTP Fetch

Fetch external data from a real API at compile time, validate the response against a typed schema, and transform it into a smaller artifact.

Source

examples/http-fetch/main.rank

/// Fetches a real Lorem API article at compile time and transforms
/// the response into a smaller summary artifact.
/// Shows HTTP::Fetch with a typed response schema, cacheKey for determinism,
/// and accessing both response.body and response.ctx metadata.

use std::HTTP
use std::Emit
use std::Path

Author = Object {
  id: string,
  name: string,
  avatar: string,
  email: string,
}

Article = Object {
  slug: string,
  title: string,
  subtitle: string,
  image: string,
  author: Author,
  content: string,
  dateCreated: string,
}

ArticleSummary = Object {
  slug: string,
  title: string,
  subtitle: string,
  author: Object {
    name: string,
    email: string,
  },
  coverImage: string,
  publishedAt: string,
  status: number,
  source: string,
}

response = HTTP::Fetch<Article> {
  url: `https://lorem-api.com/api/article/rank-http-fetch`,
  method: `GET`,
  headers: {
    Accept: `application/json`,
  },
  cacheKey: `lorem-article-rank-http-fetch-v1`,
}

article = response.body

summary: ArticleSummary = {
  slug: article.slug,
  title: article.title,
  subtitle: article.subtitle,
  author: {
    name: article.author.name,
    email: article.author.email,
  },
  coverImage: article.image,
  publishedAt: article.dateCreated,
  status: response.ctx.status,
  source: response.ctx.cacheKey,
}

pub main = || Emit::manifest({
  entries: [
    {
      path: Path::join([`article-summary.json`]),
      format: `json`,
      value: summary,
    },
  ]
})

Output

// article-summary.json
{
  "slug": "rank-http-fetch",
  "title": "Adeptio abeo cervus voluptatum delego sequi ducimus virga.",
  "subtitle": "Rerum atqui rerum et.",
  "author": {
    "name": "Shannon McDermott V",
    "email": "Fae.Gerhold@hotmail.com"
  },
  "coverImage": "https://picsum.photos/seed/RA7K2McSOQ/3074/340?blur=1",
  "publishedAt": "2020-10-01T08:13:16.355Z",
  "status": 200,
  "source": "lorem-article-rank-http-fetch-v1"
}

Key concepts

• HTTP::Fetch<T> — issues an HTTP request and validates the parsed response body against T. A schema mismatch is a compile-time error.
• Real endpoint — this example uses Lorem API's article endpoint at https://lorem-api.com/api/article/{slug} rather than a placeholder host.
• cacheKey — required for determinism. Rank stores the fetched response under this key; the same key always returns the same data within a build.
• response.body — the type-checked response body.
• response.ctx — request metadata: { status, cacheKey, headers }.
• Compile-time fetch — the request runs when Rank evaluates the program, not at application startup. The result is baked into the generated artifact.

Run it

rank examples/http-fetch/main.rank --http-cache examples/http-fetch/http-cache.json
rank examples/http-fetch/main.rank --http-cache examples/http-fetch/http-cache.json --file-root out/http-fetch

note

This example includes a checked-in snapshot at examples/http-fetch/http-cache.json. The current CLI evaluates HTTP::Fetch from snapshot data, so use --http-cache to replay the real Lorem API response deterministically in local runs and CI.