Skip to content

README.md

Latest commit

 

History

History
403 lines (341 loc) · 9.36 KB

README.md

File metadata and controls

403 lines (341 loc) · 9.36 KB

🔌 API Documentation

Complete REST API reference for CyberGuard Solutions backend services.

Overview

The CyberGuard Solutions API provides endpoints for managing security assessments, client contacts, and newsletter subscriptions. All endpoints use JSON for data exchange and include comprehensive validation and error handling.

Base URL: http://localhost:5000/api (development) | https://your-domain.com/api (production)

Authentication

Currently, the API is designed for public access with rate limiting. Authentication endpoints are prepared for future implementation.

Endpoints Overview

Endpoint Method Description Status
/assessments POST Create new security assessment ✅ Active
/assessments/:id GET Get assessment by ID ✅ Active
/assessments/:id PUT Update assessment progress ✅ Active
/contacts POST Submit contact form ✅ Active
/contacts GET List all contacts ✅ Active
/newsletters POST Subscribe to newsletter ✅ Active
/newsletters GET List newsletter subscribers ✅ Active

Security Assessments API

Create Assessment

Endpoint: POST /api/assessments

Creates a new security assessment with initial company information.

Request Body:

{
  "companySize": "51-200",
  "industry": "technology",
  "securityMeasures": [
    "Firewall Protection",
    "Antivirus Software",
    "Multi-Factor Authentication"
  ],
  "currentStep": "2",
  "responses": {}
}

Response: 201 Created

{
  "id": "uuid-generated-id",
  "companySize": "51-200",
  "industry": "technology",
  "securityMeasures": [
    "Firewall Protection",
    "Antivirus Software",
    "Multi-Factor Authentication"
  ],
  "currentStep": "2",
  "responses": {},
  "email": null,
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Get Assessment

Endpoint: GET /api/assessments/:id

Retrieves a specific assessment by its ID.

Response: 200 OK

{
  "id": "uuid-generated-id",
  "companySize": "51-200",
  "industry": "technology",
  "securityMeasures": ["Firewall Protection"],
  "currentStep": "3",
  "responses": {
    "step2": {
      "backupStrategy": "cloud-based",
      "encryptionLevel": "enterprise"
    }
  },
  "email": "client@company.com",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Update Assessment

Endpoint: PUT /api/assessments/:id

Updates assessment progress and responses.

Request Body:

{
  "currentStep": "4",
  "responses": {
    "step3": {
      "accessControl": "role-based",
      "mfaEnabled": true
    }
  },
  "email": "client@company.com"
}

Response: 200 OK

{
  "id": "uuid-generated-id",
  "companySize": "51-200",
  "industry": "technology",
  "securityMeasures": ["Firewall Protection"],
  "currentStep": "4",
  "responses": {
    "step2": {
      "backupStrategy": "cloud-based"
    },
    "step3": {
      "accessControl": "role-based",
      "mfaEnabled": true
    }
  },
  "email": "client@company.com",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Contact Management API

Submit Contact Form

Endpoint: POST /api/contacts

Submits a new contact inquiry from potential clients.

Request Body:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@company.com",
  "company": "Tech Corp",
  "companySize": "51-200",
  "industry": "technology",
  "servicesNeeded": [
    "Security Assessment",
    "Network Security",
    "Employee Training"
  ],
  "message": "We need a comprehensive security assessment for our growing tech company."
}

Response: 201 Created

{
  "id": "uuid-generated-id",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@company.com",
  "company": "Tech Corp",
  "companySize": "51-200",
  "industry": "technology",
  "servicesNeeded": [
    "Security Assessment",
    "Network Security",
    "Employee Training"
  ],
  "message": "We need a comprehensive security assessment for our growing tech company.",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

List Contacts

Endpoint: GET /api/contacts

Retrieves all contact submissions (admin access).

Response: 200 OK

[
  {
    "id": "uuid-generated-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@company.com",
    "company": "Tech Corp",
    "companySize": "51-200",
    "industry": "technology",
    "servicesNeeded": ["Security Assessment"],
    "message": "Security assessment needed",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
]

Newsletter API

Subscribe to Newsletter

Endpoint: POST /api/newsletters

Subscribes an email address to the newsletter.

Request Body:

{
  "email": "subscriber@company.com"
}

Response: 201 Created

{
  "id": "uuid-generated-id",
  "email": "subscriber@company.com",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

List Newsletter Subscribers

Endpoint: GET /api/newsletters

Retrieves all newsletter subscribers (admin access).

Response: 200 OK

[
  {
    "id": "uuid-generated-id",
    "email": "subscriber@company.com",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
]

Error Responses

All endpoints return consistent error responses:

Validation Error

Status: 400 Bad Request

{
  "message": "Invalid data",
  "errors": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["firstName"],
      "message": "Required"
    }
  ]
}

Not Found Error

Status: 404 Not Found

{
  "message": "Assessment not found"
}

Server Error

Status: 500 Internal Server Error

{
  "message": "Internal server error"
}

Data Models

Assessment Schema

{
  id: string;                           // UUID
  companySize: string;                  // "1-50" | "51-200" | "201-1000" | "1000+"
  industry: string;                     // Industry classification
  securityMeasures: string[];           // Array of current security measures
  currentStep: string;                  // Current assessment step
  responses: Record<string, any>;       // Step responses object
  email?: string;                       // Optional contact email
  createdAt: Date;                      // Creation timestamp
}

Contact Schema

{
  id: string;                           // UUID
  firstName: string;                    // Contact first name
  lastName: string;                     // Contact last name
  email: string;                        // Contact email
  company: string;                      // Company name
  companySize?: string;                 // Optional company size
  industry?: string;                    // Optional industry
  servicesNeeded: string[];             // Array of requested services
  message?: string;                     // Optional additional message
  createdAt: Date;                      // Creation timestamp
}

Newsletter Schema

{
  id: string;                           // UUID
  email: string;                        // Subscriber email (unique)
  createdAt: Date;                      // Subscription timestamp
}

Rate Limiting

API endpoints are protected with rate limiting:

  • Assessment endpoints: 10 requests per minute per IP
  • Contact submission: 5 requests per minute per IP
  • Newsletter subscription: 3 requests per minute per IP
  • List endpoints: 20 requests per minute per IP

Rate limit headers are included in responses:

  • X-RateLimit-Limit: Request limit
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Time until limit resets

Request/Response Examples

Using cURL

Create Assessment:

curl -X POST http://localhost:5000/api/assessments \
  -H "Content-Type: application/json" \
  -d '{
    "companySize": "51-200",
    "industry": "technology",
    "securityMeasures": ["Firewall Protection"],
    "currentStep": "2",
    "responses": {}
  }'

Submit Contact Form:

curl -X POST http://localhost:5000/api/contacts \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@company.com",
    "company": "Tech Corp",
    "servicesNeeded": ["Security Assessment"]
  }'

Using JavaScript Fetch

// Create assessment
const assessment = await fetch('/api/assessments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    companySize: '51-200',
    industry: 'technology',
    securityMeasures: ['Firewall Protection'],
    currentStep: '2',
    responses: {}
  })
});

const data = await assessment.json();

Future Enhancements

Planned Features

  • Authentication: JWT-based API authentication
  • Webhooks: Real-time event notifications
  • File Uploads: Document and certificate uploads
  • Advanced Filtering: Query parameters for list endpoints
  • Pagination: Large dataset pagination support
  • API Versioning: Version-specific endpoint support

Security Enhancements

  • API Key Authentication: Secure API access management
  • Request Signing: HMAC-based request verification
  • IP Whitelisting: Restricted access by IP address
  • Audit Logging: Comprehensive API access logging

This API documentation is automatically generated and maintained alongside the codebase.

API Version: 1.2.0
Last Updated: January 15, 2024