nhcarrigan/docs
9
0
Fork 0
generated from nhcarrigan/template
Code Issues 2 Pull Requests 6 Actions Releases 1 Activity

feat: time for another audit/overhaul/revamp (#13)
Node.js CI / Lint and Test (push) Successful in 1m56s
Details

Browse Source 
### Explanation

_No response_

### Issue

Closes #11

### Attestations

- [ ] I have read and agree to the [Code of Conduct](https://docs.nhcarrigan.com/community/coc/)
- [ ] I have read and agree to the [Community Guidelines](https://docs.nhcarrigan.com/community/guide/).
- [ ] My contribution complies with the [Contributor Covenant](https://docs.nhcarrigan.com/dev/covenant/).

### Dependencies

- [ ] I have pinned the dependencies to a specific patch version.

### Style

- [ ] I have run the linter and resolved any errors.
- [ ] My pull request uses an appropriate title, matching the conventional commit standards.
- [ ] My scope of feat/fix/chore/etc. correctly matches the nature of changes in my pull request.

### Tests

- [ ] My contribution adds new code, and I have added tests to cover it.
- [ ] My contribution modifies existing code, and I have updated the tests to reflect these changes.
- [ ] All new and existing tests pass locally with my changes.
- [ ] Code coverage remains at or above the configured threshold.

### Documentation

_No response_

### Versioning

_No response_

Reviewed-on: #13
Co-authored-by: Naomi Carrigan <commits@nhcarrigan.com>
Co-committed-by: Naomi Carrigan <commits@nhcarrigan.com>
This commit was merged in pull request #13.
This commit is contained in:
Naomi Carrigan
2025-11-13 21:59:23 -08:00
committed by Naomi Carrigan
parent 78ea7cc209
commit f8f787bde9
113 changed files with 6384 additions and 4254 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/content/docs/projects/data-api.md
+46 -47
View File
@@ -2,13 +2,13 @@
title: Data API
---
Data API (hereinafter the "Application") is a lightweight web API server designed to host and serve personal and professional data for the NHCarrigan ecosystem. The Application acts as a centralized headless CMS, providing structured data in both YAML and JSON formats to power multiple websites, applications, and Discord bots.
Data API (hereinafter the "Application") is a lightweight web API server designed to host and serve personal and professional data for the NHCarrigan ecosystem. The Application acts as a centralised headless CMS, providing structured data in both YAML and JSON formats to power multiple websites, applications, and Discord bots.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### 1.1 API Overview
### 1.1. API Overview
The Data Server provides a RESTful API that serves various categories of data through simple HTTP GET requests. All endpoints support both YAML and JSON formats.
@@ -17,7 +17,7 @@ The Data Server provides a RESTful API that serves various categories of data th
**Root Endpoint**:
- `GET /` - Returns a welcome message: "Welcome to the NHCarrigan Data API!"
### 1.2 Available Endpoints
### 1.2. Available Endpoints
All data endpoints are available in two formats by changing the file extension:
@@ -60,7 +60,7 @@ Contains professional testimonials and recommendations with:
Contains details about donation platforms:
- Platform names and URLs
- Icon references
- Color schemes
- Colour schemes
- Platform descriptions
#### Funding Information
@@ -74,21 +74,21 @@ Contains detailed funding information:
- Subscription plan details
- Financial history and records
### 1.3 CORS Support
### 1.3. CORS Support
The Application has CORS enabled for all origins, allowing consumption from any domain without cross-origin restrictions.
### 1.4 Content Types
### 1.4. Content Types
The Application automatically sets appropriate Content-Type headers:
- JSON endpoints: `application/json`
- YAML endpoints: `text/yaml` or `application/x-yaml`
### 1.5 Rate Limiting
### 1.5. Rate Limiting
Currently, the Application does not implement rate limiting. Users should be respectful of the server resources and avoid excessive requests.
### 1.6 Data Freshness
### 1.6. Data Freshness
Data is compiled from YAML source files during the build process. To receive updated data, the server must be rebuilt and restarted when source data changes.
@@ -96,7 +96,7 @@ Data is compiled from YAML source files during the build process. To receive upd
This section is for those interested in running their own instance of the Application.
### 2.1 Prerequisites
### 2.1. Prerequisites
Before running the Application, ensure you have the following installed:
@@ -104,7 +104,7 @@ Before running the Application, ensure you have the following installed:
- **pnpm**: Version 10.17.0 (specified in package.json as packageManager)
- **1Password CLI** (optional): For secure environment variable management in production
### 2.2 Technology Stack
### 2.2. Technology Stack
- **Runtime**: Node.js with ES modules
- **Language**: TypeScript 5.9.2
@@ -114,7 +114,7 @@ Before running the Application, ensure you have the following installed:
- **Linting**: ESLint 9.36.0
- **Package Manager**: pnpm 10.17.0
### 2.3 Installation
### 2.3. Installation
1. Clone the repository:
```bash
@@ -127,7 +127,7 @@ cd data
pnpm install
```
### 2.4 Project Structure
### 2.4. Project Structure
```
/data/
@@ -157,7 +157,7 @@ pnpm install
└── package.json # Project metadata and scripts
```
### 2.5 Configuration
### 2.5. Configuration
The Application uses the following configuration points:
@@ -176,7 +176,7 @@ The Application uses the following configuration points:
- Location: `src/index.ts:30`
- Can be restricted by modifying the Fastify CORS configuration
### 2.6 Data Management
### 2.6. Data Management
#### Adding New Data Endpoints
@@ -205,7 +205,7 @@ export interface NewData {
The YAML files are the source of truth. Always edit YAML files, not JSON files, as JSON files are auto-generated.
### 2.7 Build Process
### 2.7. Build Process
The build process consists of two steps:
@@ -224,7 +224,7 @@ To run the complete build:
pnpm run build
```
### 2.8 Available Scripts
### 2.8. Available Scripts
```bash
# Build (YAML → JSON + TypeScript compilation)
@@ -243,7 +243,7 @@ pnpm run lint:spelling # Spell check YAML files
pnpm run lint:yaml # YAML validation
```
### 2.9 Testing
### 2.9. Testing
The Application includes comprehensive test coverage using Vitest.
@@ -263,7 +263,7 @@ pnpm test
Tests have a 120-second timeout to accommodate URL validation checks, which may be rate-limited.
### 2.10 Development Workflow
### 2.10. Development Workflow
1. **Make changes to data**:
- Edit YAML files in `/data` directory
@@ -296,7 +296,7 @@ Tests have a 120-second timeout to accommodate URL validation checks, which may
curl http://localhost:9999/projects.json
```
### 2.11 Deployment
### 2.11. Deployment
#### Environment Variables
@@ -327,7 +327,7 @@ Create a `prod.env` file with 1Password references for any required environment
4. **Backups**: Regularly backup the `/data` directory, as it contains the source YAML files.
### 2.12 Troubleshooting
### 2.12. Troubleshooting
#### Server won't start
- Verify port 9999 is not in use
@@ -348,7 +348,7 @@ Create a `prod.env` file with 1Password references for any required environment
This section is for expansions to our legal policies specific to the Application.
### 3.1 Data Usage and Privacy
### 3.1. Data Usage and Privacy
#### Data Served by the Application
@@ -372,7 +372,7 @@ The Application itself does not collect, store, or process any personal data fro
By enabling CORS for all origins, the Application explicitly permits third-party websites and applications to access the served data. This is intentional and by design, as the data is meant for public consumption.
### 3.2 Data Accuracy and Updates
### 3.2. Data Accuracy and Updates
The data served by the Application is maintained on a best-effort basis. While efforts are made to ensure accuracy:
@@ -385,7 +385,7 @@ Users consuming this data should:
- Cache responses responsibly
- Not rely on the Application for time-sensitive or critical decisions
### 3.3 Service Availability
### 3.3. Service Availability
The Application is provided "as-is" without guarantees of:
- Continuous availability
@@ -395,26 +395,26 @@ The Application is provided "as-is" without guarantees of:
Users should not build critical systems that depend on the Application's availability without implementing appropriate fallbacks and error handling.
### 3.4 Intellectual Property
### 3.4. Intellectual Property
#### Data Content
The data served by the Application contains information about projects, professional experience, and other content that may be subject to intellectual property rights:
- Project names, descriptions, and logos may be trademarks
- Code and software referenced may be under various open-source licenses
- Code and software referenced may be under various open-source licences
- Testimonial content remains the intellectual property of the original authors
Users consuming this data should:
- Respect intellectual property rights
- Provide proper attribution when displaying data
- Review specific licenses for any referenced projects or software
- Review specific licences for any referenced projects or software
#### Application Code
The Application's source code is licensed under the terms specified in the LICENSE.md file. Copyright is held by Naomi Carrigan.
### 3.5 Terms of Service
### 3.5. Terms of Service
The general Terms of Service can be found at: https://docs.nhcarrigan.com/#/terms
@@ -426,7 +426,7 @@ Users of the Application agree to:
- Not attempt to exploit vulnerabilities or security weaknesses
- Respect the intended public use of the data
### 3.6 Privacy Policy
### 3.6. Privacy Policy
The general Privacy Policy can be found at: https://docs.nhcarrigan.com/#/privacy
@@ -440,19 +440,19 @@ As noted in section 3.1, the Application does not collect user data. The privacy
This section is for documentation related to contributing to the Application's codebase.
### 4.1 General Contributing Guidelines
### 4.1. General Contributing Guidelines
General contributing guidelines can be found at: https://docs.nhcarrigan.com/#/contributing
Please review these guidelines before contributing to the Application.
### 4.2 Code of Conduct
### 4.2. Code of Conduct
Before interacting with the project or community, please read the [Code of Conduct](CODE_OF_CONDUCT.md).
### 4.3 Ways to Contribute
### 4.3. Ways to Contribute
#### 4.3.1 Data Contributions
#### 4.3.1. Data Contributions
If you have corrections or updates to the data served by the Application:
@@ -460,14 +460,14 @@ If you have corrections or updates to the data served by the Application:
2. **Testimonials**: If you'd like to add a testimonial, please contact through the official channels
3. **Project updates**: For updates to project information, verify you have permission to modify the data
#### 4.3.2 Code Contributions
#### 4.3.2. Code Contributions
Contributors can help improve the Application in several ways:
**Features**:
- Enhanced API endpoints
- New data validation rules
- Performance optimizations
- Performance optimisations
- Additional data format support
- API documentation improvements
@@ -483,7 +483,7 @@ Contributors can help improve the Application in several ways:
- Documentation enhancements
- Type safety improvements
### 4.4 Development Setup
### 4.4. Development Setup
1. **Fork and clone** the repository
2. **Install dependencies**: `pnpm install`
@@ -495,7 +495,7 @@ Contributors can help improve the Application in several ways:
8. **Commit and push** your changes
9. **Open a Pull Request**
### 4.5 Code Style Guidelines
### 4.5. Code Style Guidelines
#### TypeScript
@@ -531,7 +531,7 @@ export const processData = (input) => {
- Provide meaningful error messages
- Handle errors gracefully without crashing the server
### 4.6 Testing Guidelines
### 4.6. Testing Guidelines
All contributions should maintain or improve test coverage.
@@ -564,7 +564,7 @@ Before submitting a PR:
pnpm test # Run all tests
```
### 4.7 Documentation Guidelines
### 4.7. Documentation Guidelines
When contributing documentation:
@@ -573,7 +573,7 @@ When contributing documentation:
- Update relevant sections when changing functionality
- Check spelling with `pnpm run lint:spelling`
### 4.8 Pull Request Process
### 4.8. Pull Request Process
1. **Ensure all checks pass**:
- All tests pass (`pnpm test`)
@@ -592,7 +592,7 @@ When contributing documentation:
4. **Squash commits** if requested to maintain a clean git history
### 4.9 Adding New Data Categories
### 4.9. Adding New Data Categories
To add a new data category to the Application:
@@ -634,7 +634,7 @@ To add a new data category to the Application:
curl http://localhost:9999/newcategory.json
```
### 4.10 Security Considerations
### 4.10. Security Considerations
When contributing, keep security in mind:
@@ -643,20 +643,19 @@ When contributing, keep security in mind:
- Follow secure coding practices
- Report security vulnerabilities privately before opening public issues
### 4.11 Getting Help
### 4.11. Getting Help
If you need help contributing:
- Open a GitHub issue with your question
- Join the [Chat Server](http://chat.nhcarrigan.com)
- Post in the #bug-reports or #feature-requests forum channels on our Discord community
- Join the [Chat Server](https://chat.nhcarrigan.com)
- Email: `contact@nhcarrigan.com`
### 4.12 Recognition
### 4.12. Recognition
All contributors will be recognized for their contributions. Significant contributions may be highlighted in release notes and project documentation.
All contributors will be recognised for their contributions. Significant contributions may be highlighted in release notes and project documentation.
---
**Last Updated**: 2025-10-29
**Application Version**: 1.0.0
**Maintained by**: NHCarrigan