Improve README formatting
This commit is contained in:
parent
604ec5b9ad
commit
a98c96dc5a
220
README.md
220
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 += `<div class="pagination">
|
||||
<button onclick="loadPage(${data.currentPage - 1})">Previous</button>
|
||||
<span>Page ${data.currentPage} of ${data.totalPages}</span>
|
||||
<button onclick="loadPage(${data.currentPage + 1})">Next</button>
|
||||
</div>`;
|
||||
}
|
||||
}
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user