API Documentation

وثائق واجهة برمجة التطبيقات

RESTful API for third-party integrations with the NDI Assessment Platform

API Overview

Base URL: https://naduj.com/api/v1

Authentication: API Key (Header: X-API-Key)

Content Type: application/json

Rate Limiting: 100 requests per minute per API key

Security Note: All API requests require a valid API key. Contact the administrator to obtain your API key.
Authentication

Include your API key in the request header:

X-API-Key: your-api-key-here
Health Check
GET /api/v1/health

Check API service status

Authentication: Not required

Response: 
{
  "status": "healthy",
  "version": "1.0",
  "timestamp": "2024-07-01T12:00:00Z"
}
Company Management
GET /api/v1/companies

Retrieve list of companies with pagination

Parameters:
  • page (optional): Page number
  • per_page (optional): Items per page (max 100)
Example Response: 
{
  "companies": [
    {
      "id": 1,
      "name": "Sample Company",
      "industry": "Technology",
      "size": "Large",
      "contact_email": "contact@example.com",
      "contact_name": "John Doe",
      "created_at": "2024-07-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 25,
    "pages": 3
  }
}
POST /api/v1/companies

Create a new company

Request Body: 
{
  "name": "Company Name",
  "industry": "Technology",
  "size": "Large",
  "contact_email": "email@company.com",
  "contact_name": "Contact Person"
}
Response (201): 
{
  "id": 2,
  "name": "Company Name",
  "industry": "Technology",
  "size": "Large",
  "contact_email": "email@company.com",
  "contact_name": "Contact Person",
  "created_at": "2024-07-01T12:00:00Z"
}
GET /api/v1/companies/{id}

Get company details by ID

PUT /api/v1/companies/{id}

Update company information

Assessment Management
GET /api/v1/assessments

Retrieve list of assessments

Parameters:
  • page (optional): Page number
  • per_page (optional): Items per page
  • status (optional): Filter by status
  • company_id (optional): Filter by company
Example Response: 
{
  "assessments": [
    {
      "id": 1,
      "company_id": 1,
      "company_name": "Sample Company",
      "assessor_name": "Jane Smith",
      "status": "completed",
      "started_at": "2024-07-01T09:00:00Z",
      "completed_at": "2024-07-01T11:00:00Z",
      "overall_score": 75.5,
      "maturity_level": "Managed"
    }
  ]
}
POST /api/v1/assessments

Create a new assessment for a company

Request Body: 
{
  "company_id": 1,
  "assessor_name": "Jane Smith",
  "assessor_title": "Data Manager"
}
Response (201): 
{
  "id": 2,
  "company_id": 1,
  "status": "in_progress",
  "started_at": "2024-07-01T12:00:00Z"
}
Domains and Questions
GET /api/v1/domains

Get all assessment domains

Response: 
{
  "domains": [
    {
      "id": 1,
      "name_en": "Data Governance",
      "name_ar": "حوكمة البيانات",
      "description_en": "Framework for data management",
      "order_index": 1
    }
  ]
}
GET /api/v1/domains/{id}/questions

Get questions for a specific domain

Response: 
{
  "domain": { /* domain object */ },
  "questions": [
    {
      "id": 1,
      "domain_id": 1,
      "question_text_en": "Does the organization have...?",
      "question_text_ar": "هل لدى المنظمة...؟",
      "question_type": "binary",
      "is_critical": false,
      "weight": 1.0
    }
  ]
}
Answer Submission
POST /api/v1/assessments/{id}/answers

Submit answers for assessment questions

Request Body: 
{
  "answers": [
    {
      "question_id": 1,
      "answer_value": "yes",
      "comments": "Implemented last year",
      "evidence_provided": true
    },
    {
      "question_id": 2,
      "answer_value": "no",
      "comments": "Under development"
    }
  ]
}
Answer Values:
  • "yes" - Implemented
  • "no" - Not implemented
  • "na" - Not applicable
Response (200): 
{
  "message": "Successfully submitted 2 answers",
  "answers": [ /* submitted answers */ ]
}
GET /api/v1/assessments/{id}/answers

Get all answers for an assessment

Results and Analytics
GET /api/v1/assessments/{id}/results

Get assessment results and domain scores

Response: 
{
  "assessment": {
    "id": 1,
    "overall_score": 75.5,
    "maturity_level": "Managed",
    "status": "completed"
  },
  "domain_scores": [
    {
      "domain_id": 1,
      "domain_name": "Data Governance",
      "score": 80.0,
      "total_questions": 5,
      "answered_questions": 5,
      "passed_questions": 4
    }
  ]
}
GET /api/v1/assessments/{id}/analytics

Get detailed analytics and benchmarking data

Note: Only available for completed assessments

POST /api/v1/assessments/{id}/complete

Mark assessment as completed and calculate final scores

Response (200): 
{
  "message": "Assessment completed successfully",
  "assessment": { /* updated assessment object */ }
}
Platform Analytics
GET /api/v1/analytics/platform

Get platform-wide analytics and statistics

Response: 
{
  "total_assessments": 150,
  "completed_assessments": 120,
  "completion_rate": 80.0,
  "industry_distribution": [
    {
      "industry": "Technology",
      "count": 45,
      "avg_score": 78.5
    }
  ],
  "maturity_distribution": [
    {
      "level": "Managed",
      "count": 35
    }
  ]
}
Data Export
GET /api/v1/assessments/{id}/export

Export complete assessment data including answers and scores

Returns comprehensive JSON with all assessment-related data for external processing.

Error Codes
Code Description Example Response
400 Bad Request {"error": "Missing required field: name"}
401 Unauthorized {"error": "API key required"}
404 Not Found {"error": "Resource not found"}
409 Conflict {"error": "Company with this name already exists"}
429 Rate Limit Exceeded {"error": "Rate limit exceeded"}
500 Internal Server Error {"error": "Internal server error"}
API Testing
Test the API: Use tools like Postman, curl, or your preferred API client to test these endpoints.

Example curl command:

curl -X GET "https://naduj.com/api/v1/health" \
     -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json"
API Base URL
https://naduj.com/api/v1
Contact for API Key

Administrator

File Preview

Loading preview...

Download