From a98c96dc5a1fbe9c1a9c5a9d836bfe89cb02e668 Mon Sep 17 00:00:00 2001 From: David Friedel Date: Sun, 28 Dec 2025 20:41:29 +0000 Subject: [PATCH] Improve README formatting --- README.md | 220 +++++++++++++----------------------------------------- 1 file changed, 51 insertions(+), 169 deletions(-) diff --git a/README.md b/README.md index 483220e..6e16340 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,40 @@ # CiteLynq Web Sample -A sample ASP.NET Core web application demonstrating how to use the CiteLynq API to search for verified citations across multiple authoritative sources. +A sample ASP.NET Core web application demonstrating how to integrate with the CiteLynq API for verified citations across multiple authoritative sources. ## Features -✅ ASP.NET Core 9.0 minimal API -✅ Static file hosting with wwwroot -✅ Proxy endpoints to hide API keys from client -✅ Clean, modern UI with gradient design -✅ Search across multiple data sources -✅ Display formatted citations (APA, MLA, Bluebook) -✅ Filter by source type (ArXiv, PubMed, CourtListener, etc.) -✅ Responsive design -✅ Local storage for API key persistence +| Feature | Description | +|---------|-------------| +| ASP.NET Core 9.0 | Minimal API with modern C# patterns | +| Proxy Endpoints | Hide API keys from client-side code | +| Multi-Source Search | ArXiv, PubMed, CourtListener, and more | +| Citation Formats | APA, MLA, Chicago, Bluebook | +| Responsive UI | Clean, modern design for desktop and mobile | +| Local Storage | Persists API key in browser | ## Quick Start -### 1. Get an API Key +### 1. Clone the Repository -1. Visit [https://citelynq.com/app/api-keys](https://citelynq.com/app/api-keys) +```bash +git clone https://git.marketally.com/citelynq/CiteLynq.WebSample.git +cd CiteLynq.WebSample +``` + +### 2. Get an API Key + +1. Visit [citelynq.com/app/api-keys](https://citelynq.com/app/api-keys) 2. Create a new API key 3. Copy the key (starts with `cl_`) -### 2. Run the Application +### 3. Run ```bash -cd /repos/CiteFlow/samples/CiteLynq.WebSample dotnet run ``` -The application will start on `http://localhost:5100` - -### 3. Use the Application - -1. Open your browser to `http://localhost:5100` -2. Enter your API key -3. Enter a search query (e.g., "climate change") -4. Click "Search" +Open `http://localhost:5100` in your browser. ## Project Structure @@ -50,47 +48,24 @@ CiteLynq.WebSample/ └── index.html # Single-page application ``` -## How It Works - -### Backend (Program.cs) - -The backend provides proxy endpoints to securely call the CiteLynq API: - -1. **GET /api/search** - Proxies search requests - - Accepts: query parameters (q, sourceType, page, pageSize) - - Headers: X-API-Key - - Returns: Search results from CiteLynq API - -2. **GET /api/articles/{id}** - Proxies article detail requests - - Accepts: article ID as path parameter - - Headers: X-API-Key - - Returns: Article details from CiteLynq API - -**Why use a proxy?** -- Hides your API key from client-side code -- Prevents CORS issues -- Adds an abstraction layer for future enhancements -- Enables server-side caching if needed - -### Frontend (wwwroot/index.html) - -The frontend is a self-contained single-page application: - -- **API Key Storage**: Saves API key in localStorage -- **Search Interface**: Query input and source filter -- **Results Display**: Shows citations with metadata -- **Responsive Design**: Works on desktop and mobile - ## API Endpoints ### Search Citations ```http -GET /api/search?q=climate%20change&sourceType=ArXiv&page=1&pageSize=20 +GET /api/search?q=climate+change&sourceType=ArXiv&page=1&pageSize=20 X-API-Key: cl_your-api-key-here ``` -**Response:** +### Get Article Details + +```http +GET /api/articles/{id} +X-API-Key: cl_your-api-key-here +``` + +### Example Response + ```json { "data": { @@ -100,13 +75,10 @@ X-API-Key: cl_your-api-key-here "sourceType": "ArXiv", "title": "Climate Change Research", "authors": ["Dr. Jane Smith"], - "abstract": "...", "publishedDate": "2023-01-15", - "url": "https://arxiv.org/abs/2301.12345", "citations": { "apa": "Smith, J. (2023)...", - "mla": "Smith, Jane...", - "chicago": "..." + "mla": "Smith, Jane..." } } ], @@ -115,26 +87,17 @@ X-API-Key: cl_your-api-key-here } ``` -### Get Article Details - -```http -GET /api/articles/arxiv-2301.12345 -X-API-Key: cl_your-api-key-here -``` - ## Configuration -### Change API Base URL +### API Base URL -Edit `Program.cs` line 24 to point to a different API: +Edit `Program.cs`: ```csharp const string API_BASE_URL = "https://citelynq.com/api"; -// Or for local development: -// const string API_BASE_URL = "http://localhost:5000/api"; ``` -### Change Port +### Port Edit `Properties/launchSettings.json`: @@ -153,116 +116,35 @@ Edit `Properties/launchSettings.json`: ### Prerequisites - .NET 9.0 SDK -- Visual Studio 2022 / VS Code / Rider -### Build +### Commands ```bash -dotnet build -``` - -### Run - -```bash -dotnet run -``` - -### Publish - -```bash -dotnet publish -c Release -o ./publish -``` - -## Customization - -### Add More Endpoints - -Add new proxy endpoints in `Program.cs`: - -```csharp -app.MapGet("/api/sources", async (HttpContext context, IHttpClientFactory httpClientFactory) => -{ - var apiKey = context.Request.Headers["X-API-Key"].FirstOrDefault(); - var httpClient = httpClientFactory.CreateClient(); - var httpRequest = new HttpRequestMessage(HttpMethod.Get, $"{API_BASE_URL}/sources"); - httpRequest.Headers.Add("X-API-Key", apiKey); - var response = await httpClient.SendAsync(httpRequest); - return Results.Content(await response.Content.ReadAsStringAsync(), "application/json"); -}); -``` - -### Customize UI - -Edit `wwwroot/index.html`: - -```css -/* Change color scheme */ -body { - background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); -} -``` - -### Add Pagination - -Add pagination controls in the HTML: - -```javascript -function displayResults(data) { - // ... existing code ... - - if (data.totalPages > 1) { - html += ``; - } -} +dotnet build # Build +dotnet run # Run +dotnet publish -c Release # Publish ``` ## Security Notes -⚠️ **Important:** - -1. **API Key Protection**: The proxy pattern keeps API keys server-side -2. **CORS**: Configured for development (allow all origins). Restrict in production. -3. **Input Validation**: Always validate user input -4. **HTTPS**: Use HTTPS in production environments +- **API Keys**: The proxy pattern keeps keys server-side +- **CORS**: Configure specific origins for production +- **HTTPS**: Required for production deployments ## Troubleshooting -### Port Already in Use +| Issue | Solution | +|-------|----------| +| Port in use | Change port in `launchSettings.json` | +| CORS errors | Check CORS configuration in `Program.cs` | +| API key invalid | Verify key starts with `cl_` and is active | -Change the port in `Properties/launchSettings.json` +## Resources -### CORS Errors - -The application includes CORS middleware for development. For production, configure specific origins: - -```csharp -builder.Services.AddCors(options => -{ - options.AddDefaultPolicy(policy => - { - policy.WithOrigins("https://yourdomain.com") - .AllowAnyMethod() - .AllowAnyHeader(); - }); -}); -``` - -### API Key Not Working - -1. Verify the key starts with `cl_` -2. Check the key is active in your account -3. Ensure the key has available credits - -## Learn More - -- **CiteLynq API Docs**: [https://citelynq.com/docs](https://citelynq.com/docs) -- **Get API Key**: [https://citelynq.com/app/api-keys](https://citelynq.com/app/api-keys) -- **ASP.NET Core**: [https://docs.microsoft.com/aspnet/core](https://docs.microsoft.com/aspnet/core) +- [CiteLynq API Docs](https://citelynq.com/docs) +- [Get API Key](https://citelynq.com/app/api-keys) +- [ASP.NET Core Docs](https://docs.microsoft.com/aspnet/core) ## License -This sample is provided as-is for demonstration purposes. +MIT - Use freely in your own projects.