The PGNC REST API provides programmatic access to the PGNC (Plant Gene Nomenclature Committee) gene database. Built with NestJS 10.x, this API enables efficient querying, searching, and management of plant gene nomenclature data through RESTful endpoints.

• Gene Data Access: Comprehensive access to gene symbols, names, locations, and cross-references
• Search Integration: Direct integration with Apache Solr 9.9.0 for fast full-text search
• Authentication: JWT-based authentication with configurable token lifetimes
• Database Integration: TypeORM integration with PostgreSQL 17.0
• API Documentation: Automated OpenAPI/Swagger documentation
• Health Monitoring: Built-in health check endpoints
• Email Integration: Nodemailer integration for notifications

• Framework: NestJS 10.x
• Runtime: Node.js (LTS)
• Database: PostgreSQL 17.0 with TypeORM
• Authentication: JWT tokens with bcrypt password hashing
• Documentation: Swagger/OpenAPI 3.0
• Testing: Jest testing framework
• Validation: class-validator and class-transformer

• Node.js (LTS version recommended)
• PostgreSQL 17.0 database
• Environment configuration (.env file)

1. Install dependencies:

   cd api
   npm install

2. Configure environment: Copy .env from parent directory or configure these variables:

   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=pgnc_database
   DB_USER=postgres
   DB_PASSWORD=your_password
   JWT_SECRET=your_jwt_secret
   API_PORT=3000

3. Start the development server:

   npm run start:dev

All protected API requests require a valid JWT token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

• Development: http://localhost:3000/api
• Production: https://plant.genenames.org/api
• Documentation: http://localhost:3000/api (Swagger UI)

The API provides comprehensive endpoints for gene data access. Full documentation is available via Swagger UI at the base URL.

• Health Check: GET /health - Service health status
• Gene Search: GET /genes - Search and filter genes
• Gene Details: GET /genes/{id} - Get specific gene information
• Gene Symbols: GET /genes/{id}/symbols - Get gene symbol history
• Gene Names: GET /genes/{id}/names - Get gene name history
• Cross References: GET /genes/{id}/xrefs - Get external database references

• Full-text Search: GET /search - Powered by Solr integration
• Autocomplete: GET /suggest - Gene symbol/name suggestions
• Faceted Search: GET /search/facets - Search with filters

The API runs as part of the Docker Compose stack:

# Start API service
docker compose up -d api

# View API logs
docker compose logs -f api

# Access API documentation
open http://localhost:3000/api

# Unit tests
npm run test

# End-to-end tests
npm run test:e2e

# Test coverage
npm run test:cov

# Linting
npm run lint

# Format code
npm run format

# Generate documentation
npm run doc

The API uses TypeORM for database operations:

• Auto-sync: Disabled in production (DB_SYNC=false)
• Migrations: Manual migration management
• Entities: Defined in src/ directories

Key configuration options:

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=pgnc_database
DB_USER=postgres
DB_PASSWORD=your_password
DB_SYNC=false
DB_AUTOLOAD_ENTITIES=true

# JWT Configuration
JWT_SECRET=your_secret_key
JWT_TOKEN_AUDIENCE=pgnc-api
JWT_TOKEN_ISSUER=pgnc
JWT_ACCESS_TOKEN_TTL=3600
JWT_REFRESH_TOKEN_TTL=86400

# Email Configuration
MAIL_HOST=smtp.example.com
SMTP_USERNAME=your_email
SMTP_PASSWORD=your_password

# Server Configuration
API_PORT=3000

• Password Hashing: bcrypt with configurable rounds
• JWT Tokens: Configurable expiration and refresh
• CORS: Configured for frontend integration
• Rate Limiting: Built-in protection against abuse

The API returns standardized error responses:

{
  "statusCode": 400,
  "message": "Error description",
  "error": "Bad Request",
  "timestamp": "2025-09-11T10:00:00.000Z",
  "path": "/api/endpoint"
}

• 200: Success
• 201: Created
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 429: Too Many Requests
• 500: Internal Server Error

The API integrates seamlessly with the Angular 19.1+ frontend:

• Proxy Configuration: Development proxy in angular/proxy.conf.json
• CORS: Configured for cross-origin requests
• Authentication: JWT token management
• Type Safety: Shared TypeScript interfaces

Direct integration with Apache Solr 9.9.0:

• Solr Client: Custom service for Solr communication
• Index Synchronization: Automated via Python 3.13+ data pipeline
• Search Optimization: Cached queries and optimized search parameters

• Database: Connection and query health
• Dependencies: External service availability
• Memory: Resource usage monitoring

• Request Logging: All API requests logged
• Error Tracking: Detailed error information
• Performance: Response time monitoring

The API is deployed as part of the Docker Compose stack with:

• Auto-restart: Service restarts on failure
• Health monitoring: Docker health checks
• Load balancing: Nginx reverse proxy
• SSL termination: Let's Encrypt certificates

1. Follow NestJS coding conventions
2. Write comprehensive tests
3. Update API documentation
4. Ensure type safety
5. Test with Docker environment

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.