developers

APIs, OpenAPI 3.1.0 specification, Model Context Protocol (MCP) server, official multi-language SDKs (npm, PyPI, Go, RubyGems), and integration guides for developers and AI agents.

All read-only REST and agent interfaces on ashwingopalsamy.in operate with zero onboarding friction. No API keys, payment methods, or authentication credentials are required for standard discovery.

The live endpoints serve as an open sandbox environment returning deterministic, authoritative data with sub-second latency budgets.

OpenAPI 3.1.0 SpecDesign DetailsAI briefing

Official Multi-Language SDKs

Official client packages auto-generated and validated against the OpenAPI 3.1.0 specification, featuring verified package homepages pointing to https://ashwingopalsamy.in/developers:

npm · TypeScript
npm install @ashwingopalsamy/sdk
import { AshwinGopalsamyClient } from "@ashwingopalsamy/sdk";

const client = new AshwinGopalsamyClient();
const profile = await client.getProfile();
const results = await client.searchSite("rate limiters", 5);
pip install ashwingopalsamy
from ashwingopalsamy import Client

client = Client()
profile = client.get_profile()
results = client.search_site("rate limiters", limit=5)
go get github.com/ashwingopalsamy/site/packages/go
import (
    "context"
    ashwingopalsamy "github.com/ashwingopalsamy/site/packages/go"
)

client := ashwingopalsamy.NewClient()
profile, err := client.GetProfile(ctx)
results, err := client.SearchSite(ctx, "rate limiters", 5)
gem install ashwingopalsamy
require "ashwingopalsamy"

client = AshwinGopalsamy::Client.new
profile = client.get_profile
results = client.search_site("rate limiters", limit: 5)

Official CLI Tool (ashwingopalsamy)

Script interactions with Ashwin Gopalsamy's profile, notes, and search index directly from your terminal or automation pipeline:

NPX / Node.jsZero-install Node CLI for profile inspection, global search, and note retrieval.
npx ashwingopalsamy profile
npx ashwingopalsamy search "rate limiters"
npx ashwingopalsamy note designing-rate-limiters-for-payment-systems
Curl / POSIX ShellLightweight POSIX shell runner for Unix environments without Node installed.
curl -sSL https://ashwingopalsamy.in/cli.sh | sh -s -- profile
curl -sSL https://ashwingopalsamy.in/cli.sh | sh -s -- search "ISO 8583"

REST v1 Endpoints

Base: https://ashwingopalsamy.in/api/v1
GET/api/v1/profile

Authoritative career summary, current role, location, and verified profile facts.

GET/api/v1/search?query={q}&limit={n}

Search technical notes, craft projects, and reading list entries.

GET/api/v1/content?kind={kind}&limit={n}

List public entries by kind (note, craft, book, watch, or all).

GET/api/v1/notes/{slug}

Retrieve raw Markdown content and metadata for a published note.

GET/api/v1/status

API operational status, versioning policy, and capability catalog.

Protocol Interfaces (MCP, A2A & Web Bot Auth)

Model Context Protocol (MCP)

/mcp
Streamable HTTP · JSON-RPC 2.0

Production MCP endpoint offering native tool execution (search_site, get_profile, list_content, get_note_markdown), resources, and prompt templates for autonomous AI agents.

npx -y @modelcontextprotocol/inspector https://ashwingopalsamy.in/mcp

Agent-to-Agent (A2A)

/a2a
JSON-RPC 2.0 Task Routing

Direct agent message exchange protocol for task delegation, profile extraction, and capability handoff.

curl -s -X POST https://ashwingopalsamy.in/a2a -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"parts":[{"kind":"text","text":"profile"}]}}}'

OpenAPI Specification

/openapi.json
OpenAPI 3.1.0

Complete machine-readable REST API schema defining strongly typed parameters, request contracts, and response schemas.

curl -s https://ashwingopalsamy.in/openapi.json

Web Bot Auth Directory (RFC 9421)

/.well-known/http-message-signatures-directory
RFC 9421 · Ed25519 JWK

Cryptographic public signature keys directory for verifying authentic bot identities and mitigating spoofing.

curl -s https://ashwingopalsamy.in/.well-known/http-message-signatures-directory

Web Bot Authentication (RFC 9421 HTTP Signatures)

Legitimate automated agents and bots can sign HTTP requests according to RFC 9421 (HTTP Message Signatures). Ashwin Gopalsamy's public signing directory is published at /.well-known/http-message-signatures-directory.

The directory exposes Ed25519 JSON Web Keys with validity timestamps (nbf, exp) to cryptographically distinguish genuine bot agents from spoofers.

Headers & Rate Limiting

All REST and agent endpoints return standard IETF RateLimit and legacy X-RateLimit headers so agents can self-throttle in real time:

RateLimit-Limit120
Maximum requests permitted per sliding window (120 per minute).
RateLimit-Remaining0..120
Remaining request budget available in the active window.
RateLimit-Reset60s
Seconds remaining until current window quota fully resets.
RateLimit-Policy120;w=60
Standard IETF quota policy descriptor (120 req / 60s window).
X-RateLimit-*Legacy
Compatibility headers provided for legacy HTTP clients and proxies.
API-Version2026-08-22
Contract release timestamp defining endpoint behavior.

If a client exceeds quota, the server responds with HTTP 429 Too Many Requests and includes a Retry-After header with the required wait duration.

API Versioning & Deprecation Policy

Ashwin Gopalsamy's API employs explicit URL versioning (/api/v1/...) combined with response version headers:

Path Versioning/api/v1
Major revisions use dedicated URL prefixes. Non-breaking extensions preserve route stability.
Deprecation SignalingRFC 9594 & 8594
Retiring routes broadcast standard Deprecation and Sunset headers with targeted decommission dates.
Notice Window6 Months
Breaking contract changes require a minimum 6-month advance notice before sunset.

Typed Error Model (RFC 9457)

All error responses follow the RFC 9457 Problem Details standard (application/problem+json) with structured error codes and actionable resolution hints:

{
  "type": "https://ashwingopalsamy.in/developers#errors",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "Note slug 'non-existent' was not found in published index.",
  "code": "note_not_found",
  "resolution_hint": "Check /api/v1/content?kind=note for a complete list of valid note slugs."
}

Scoped Permissions & Security Schemes

OAuth 2.0 discovery metadata is published at /.well-known/oauth-protected-resource and /auth.md. Supported permission scopes:

site.readRead-Only
Unrestricted read access to public profiles, craft projects, and technical notes.
profile.readRead-Only
Access verified identity facts, career history, and current employment metadata.
content.searchRead-Only
Execute semantic and keyword queries across technical notes and library entries.
notes.readRead-Only
Retrieve raw Markdown source and frontmatter for published technical notes.

Developer & Machine Discovery Index

Direct links to all machine-readable catalogs, feeds, and discovery surfaces:

Developer APIs & Specifications

AI & Agent Discovery

LLM Context & Machine Catalogs