Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PDNMX/s1_backend/llms.txt

Use this file to discover all available pages before exploring further.

S1 Backend is a Node.js/Express REST API that acts as an aggregation gateway between PDN front-end applications and a network of federated government data providers. Each provider independently hosts asset declaration records for public servants under their jurisdiction. Rather than requiring clients to query every provider individually, S1 Backend exposes a single, uniform interface that fans out requests across the registered provider network, acquires OAuth 2.0 tokens per provider, and returns a consolidated response — all in a single round-trip for the caller.

​
Context: PDN Sistema 1

Mexico’s Plataforma Digital Nacional (PDN) is a national anti-corruption transparency platform that surfaces public information across six systems. Sistema 1 focuses on asset declarations (declaraciones patrimoniales) submitted by public servants at federal, state (estatal), and municipal (municipal) levels. Because these records are held by dozens of independent institutions — each operating its own API — a gateway layer is essential to provide unified access without coupling clients to the ever-changing provider landscape.

​
Architectural Role

S1 Backend sits between PDN-facing user interfaces (or any HTTP client) and the federated government data suppliers:
  1. Provider registry — On startup the gateway reads endpoints.json, which lists every registered provider along with its OAuth 2.0 credentials, API URLs, and coverage levels.
  2. Request filtering — Incoming queries may be scoped by nivel_gobierno (government level: federal, estatal, municipal) or by a specific institution (supplier_id). The gateway filters the provider list accordingly.
  3. Token acquisition — For each selected provider the gateway calls getToken() in routes/rest_data.js, performing an OAuth 2.0 password-grant flow against the provider’s token_url.
  4. Fan-out queries — All provider calls are dispatched in parallel via Promise.all(), each sending a POST request with the query options and a Bearer token in the Authorization header.
  5. Aggregation — Responses are merged into a single array and returned to the caller. Per-provider errors are isolated and returned alongside successful responses so a single failing provider does not suppress results from the rest.

​
HTTP Endpoints

S1 Backend exposes five routes:
MethodPathDescription
GET/Health check — returns API title and version.
GET/v1/providersLists all registered providers with their IDs, names, levels, and status.
POST/v1/summaryFan-out count query across providers. Returns pagination metadata per provider for name-based filtering.
POST/v1/searchDetailed paginated search against a single specified provider (supplier_id required).
POST/v1/loggerAccepts client-side log entries and writes them through log4js.
Before starting the server you must create endpoints.json from the provided endpoints.json.example template and populate it with real provider credentials. The application will fail to load if this file is missing.

​
Quick Navigation

Quickstart

Run the gateway locally and make your first API call in five steps.

Configuration

Full reference for .env and the endpoints.json provider registry schema.

API Reference

Detailed documentation for every endpoint, request body, and response shape.

Docker Deployment

Containerise and deploy S1 Backend with Docker or Docker Compose.

​
How It Works

The diagram below traces the life of a /v1/summary request end-to-end: 
Client
  │
  │  POST /v1/summary  { nivel_gobierno: "estatal", nombres: "Juan" }
  ▼
S1 Backend (Express)
  │
  ├─ Filter endpoints.json → providers where levels includes "estatal"
  │
  ├─ For each provider (in parallel):
  │     │
  │     ├─ POST {token_url}  grant_type=password  → access_token
  │     │
  │     └─ POST {url}  Authorization: Bearer <token>  { page, pageSize, query }
  │           │
  │           └─ Provider API response
  │
  └─ Promise.all() aggregates all responses
        │
        └─ [ { supplier_id, supplier_name, pagination, results }, … ]
  │
  ▼
Client receives consolidated JSON array
Individual provider failures are caught per-promise. A failing provider returns an error object — including supplier_id, supplier_name, levels, and a totalRows: "No disponible" marker — while all other providers continue to contribute their results normally.

​
Technology Stack

PackageRole
Node.jsJavaScript runtime
Express 4HTTP server and router (express ~4.16.0)
axiosHTTP client for provider token and data requests (^1.6.0)
log4jsStructured application logging (^6.4.0)
dotenvLoads PORT from .env into process.env (^8.2.0)
corsCORS middleware applied globally to all routes (^2.8.5)
qsURL-encodes OAuth token request bodies (^6.9.7)
morganHTTP request logging in development (~1.9.0)
nodemonAuto-restart on file changes during development (^2.0.3)

Build docs developers (and LLMs) love

Get started for freeTalk to us