Skip to content

API.md

Latest commit

 

History

History
275 lines (207 loc) · 5.91 KB

API.md

File metadata and controls

275 lines (207 loc) · 5.91 KB
Raw

Research Database API

The research system now provides API endpoints that return data in both JSON and Markdown formats, making it usable as a database for Ontic developers.

Available Endpoints

1. List All Research Posts

JSON Format (default):

GET /api/research
GET /api/research?format=json

Returns:

{
  "total": 3,
  "posts": [
    {
      "id": "ambient-intelligence",
      "title": "Building Ambient Intelligence",
      "date": "FEBRUARY 14, 2026",
      "category": "ENGINEERING",
      "description": "An architectural overview...",
      "url": "/api/research/ambient-intelligence",
      "jsonUrl": "/research/ambient-intelligence.json"
    },
    ...
  ]
}

Markdown Format:

GET /api/research?format=markdown
GET /api/research?format=md

Returns a markdown document with all posts listed with their metadata.

2. Get Individual Research Post (Markdown)

GET /api/research/[id]

Example:

GET /api/research/ambient-intelligence

Returns:

---
id: ambient-intelligence
title: Building Ambient Intelligence
date: FEBRUARY 14, 2026
category: ENGINEERING
description: An architectural overview of building systems...
---

# Building Ambient Intelligence

**Category:** ENGINEERING  
**Date:** FEBRUARY 14, 2026

An architectural overview of building systems that run continuously...

---

## What is Ambient Intelligence?

Ambient intelligence refers to systems that operate seamlessly...

3. Get Individual Research Post (JSON)

GET /research/[id].json

Example:

GET /research/ambient-intelligence.json

Returns the raw JSON file.

Usage Examples

Fetch All Posts in JSON

const response = await fetch('/api/research');
const data = await response.json();
console.log(data.posts);

Fetch All Posts as Markdown

const response = await fetch('/api/research?format=markdown');
const markdown = await response.text();
console.log(markdown);

Fetch Individual Post as Markdown

const response = await fetch('/api/research/ambient-intelligence');
const markdown = await response.text();
console.log(markdown);

Using in Developer Tools

cURL example:

# Get all posts as JSON
curl https://your-domain.vercel.app/api/research

# Get all posts as Markdown
curl https://your-domain.vercel.app/api/research?format=markdown

# Get specific post as Markdown
curl https://your-domain.vercel.app/api/research/ambient-intelligence

# Get specific post as JSON
curl https://your-domain.vercel.app/research/ambient-intelligence.json

PowerShell example:

# Get all posts as JSON
Invoke-RestMethod -Uri "https://your-domain.vercel.app/api/research"

# Get specific post as Markdown
Invoke-WebRequest -Uri "https://your-domain.vercel.app/api/research/ambient-intelligence" | Select-Object -ExpandProperty Content

Use Cases for Developers

  1. Documentation Integration: Import research posts into documentation sites
  2. CI/CD Pipelines: Fetch latest research for automated reports
  3. Developer Tools: Build tools that reference research posts
  4. Knowledge Base: Use as a queryable knowledge database
  5. AI/LLM Context: Feed research posts to AI models for context
  6. Static Site Generation: Pull research data for static site builds

Response Headers

Markdown Endpoints

  • Content-Type: text/markdown; charset=utf-8
  • Content-Disposition: inline; filename="[id].md"

JSON Endpoints

  • Content-Type: application/json

Error Responses

404 Not Found

{
  "error": "Post not found"
}

400 Bad Request

{
  "error": "Invalid post ID"
}

500 Internal Server Error

{
  "error": "Failed to load research post"
}

Integration Examples

React Component

import { useEffect, useState } from 'react';

function ResearchList() {
  const [posts, setPosts] = useState([]);

  useEffect(() => {
    fetch('/api/research')
      .then(res => res.json())
      .then(data => setPosts(data.posts));
  }, []);

  return (
    <div>
      {posts.map(post => (
        <div key={post.id}>
          <h3>{post.title}</h3>
          <p>{post.description}</p>
          <a href={post.url}>Read Markdown</a>
        </div>
      ))}
    </div>
  );
}

Node.js Script

const fetch = require('node-fetch');

async function getResearchPosts() {
  const response = await fetch('https://your-domain.vercel.app/api/research');
  const data = await response.json();
  
  for (const post of data.posts) {
    console.log(`${post.title} (${post.category})`);
    
    // Get full markdown content
    const mdResponse = await fetch(`https://your-domain.vercel.app${post.url}`);
    const markdown = await mdResponse.text();
    
    // Save to file or process
    console.log(markdown.substring(0, 200) + '...');
  }
}

getResearchPosts();

Python Script

import requests

# Get all posts
response = requests.get('https://your-domain.vercel.app/api/research')
data = response.json()

for post in data['posts']:
    print(f"{post['title']} ({post['category']})")
    
    # Get markdown content
    md_response = requests.get(f"https://your-domain.vercel.app{post['url']}")
    markdown = md_response.text
    
    # Save to file
    with open(f"{post['id']}.md", 'w', encoding='utf-8') as f:
        f.write(markdown)

Local Development

When running locally (http://localhost:5174), the API endpoints are also available:

http://localhost:5174/api/research
http://localhost:5174/api/research?format=markdown
http://localhost:5174/api/research/ambient-intelligence
http://localhost:5174/research/ambient-intelligence.json

Notes

  • All markdown responses use UTF-8 encoding
  • View counts are tracked client-side in localStorage
  • The markdown format includes YAML frontmatter for metadata
  • Posts are automatically sorted by date (newest first)
  • The API reads directly from the filesystem (/public/research/)