Low Resource Language Library API

ASP.NET 8 Web API that serves Croissant 1.0 JSON-LD responses from a SQLite/PostgreSQL database of Chichewa metadata.

---

Project structure

llrp-api/
├── Controllers/
│   └── DatasetsController.cs     # GET /api/datasets/query  +  /health
├── Data/
│   ├── AppDbContext.cs            # EF Core context
│   └── Models/Models.cs          # Dataset, FileRecord, Keyword, Theme
├── DTOs/
│   └── DatasetQueryParams.cs     # Query string parameters
├── Middleware/
│   └── ApiKeyMiddleware.cs       # X-Api-Key enforcement
├── Services/
│   ├── FileQueryService.cs       # DB query + random sampling
│   └── CroissantBuilder.cs       # JSON-LD serialiser
├── appsettings.json              # Connection string + API keys (production)
├── appsettings.Development.json  # Overrides for local dev
└── Program.cs                    # DI + middleware pipeline

---

Quick start

1. Configure API keys

Edit appsettings.json (or use User Secrets / environment variables in production):

{
  "ApiKeys": [
    "your-secret-key-here"
  ]
}

Environment variable override (no quotes needed):

ApiKeys__0=your-secret-key-here
ApiKeys__1=another-key

2. Run the API

cd llrp-api
dotnet run

The API starts on https://localhost:5001 / http://localhost:5000.

---

Swagger UI

Open http://localhost:5000/swagger in your browser.

1. Click Authorize (top right)
2. Enter your API key (e.g. dev-key-12345)
3. Click Authorize → Close
4. All requests from Swagger UI will now include the X-Api-Key header

---

Endpoints

GET /api/datasets/query

Returns a Croissant JSON-LD document. All parameters are optional.

Parameter	Type	Default	Description
keyword	string	—	Partial, case-insensitive keyword match
theme	string	—	Partial, case-insensitive UNBIS theme match
author	string	—	Partial, case-insensitive author name match
year	string	—	Exact year, e.g. 2024
limit	int	30	Max files in response (1–100). Random sample taken when total > limit

Example requests:

# All files tagged with "malaria", limit 10
curl -H "X-Api-Key: dev-key-12345" \
     "http://localhost:5000/api/datasets/query?keyword=malaria&limit=10"

# Health and Education files from 2024
curl -H "X-Api-Key: dev-key-12345" \
     "http://localhost:5000/api/datasets/query?theme=Health&year=2024"

# Combine filters
curl -H "X-Api-Key: dev-key-12345" \
     "http://localhost:5000/api/datasets/query?keyword=election&theme=Political&author=Banda&limit=5"

GET /api/datasets/health

Returns API status and total file count. Also requires X-Api-Key.

curl -H "X-Api-Key: dev-key-12345" http://localhost:5000/api/datasets/health

---

Response format

{
  "@context": [ "https://mlcommons.org/working-groups/data/croissant/", { ... } ],
  "generatedAt": "2026-02-27T10:00:00Z",
  "samplingInfo": {
    "totalMatched": 120,   // files that matched the query
    "limit": 30,           // requested limit
    "returned": 30,        // files in this response
    "randomSample": true   // true when totalMatched > limit
  },
  "@graph": [
    {
      "@type": "sc:Dataset",
      "@id": "DDP-NATION-2024",
      "scName": "Nation Newspaper 2024",
      "distribution": [
        {
          "@type": "cr:FileObject",
          "@id": "file-2024-abc123",
          "scName": "Nation_On_Sunday_20240315_p001.pdf",
          "scKeywords": ["malaria", "hospital"],
          "dcatTheme": ["Health"],
          ...
        }
      ]
    }
  ]
}

---

Security notes

• API keys live in appsettings.json → ApiKeys array
• In production, inject keys via environment variables or a secrets manager — never commit real keys to source control
• Swagger UI is exempt from the key gate so the docs page loads freely, but every API call made through it still requires a valid key
• Consider rate limiting (e.g. AspNetCoreRateLimit package) for public-facing deployments