Entity Creation API

Overview

The Entity Creation API allows authenticated users to create new entities in the Ring Platform. This endpoint supports creating various types of entities including companies, organizations, and projects with comprehensive metadata and visibility controls.

Endpoint Details

• URL: /api/entities/create
• Method: POST
• Authentication: Required (JWT Token)
• Rate Limit: 60 requests per minute for authenticated users
• Content-Type: application/json

Authentication Requirements

This endpoint requires authentication with one of the following roles:

• ADMIN - Full access to create any entity type
• CONFIDENTIAL - Can create confidential entities
• MEMBER - Can create public and member-visible entities

Request Format

Headers

POST /api/entities/create
Content-Type: application/json
Authorization: Bearer <jwt_token>

Request Body Schema

interface CreateEntityRequest {
  name: string;                    // Entity name (required)
  description?: string;            // Entity description
  website?: string;               // Official website URL
  email?: string;                 // Contact email
  phone?: string;                 // Contact phone number
  address?: string;               // Physical address
  category: string;               // Entity category
  tags?: string[];                // Searchable tags
  visibility: 'public' | 'member' | 'confidential'; // Visibility level
  logo?: string;                  // Logo URL
  socialLinks?: {                 // Social media links
    linkedin?: string;
    twitter?: string;
    facebook?: string;
    github?: string;
  };
  foundedYear?: number;           // Year founded
  employeeCount?: string;         // Employee count range
  industry?: string;              // Industry classification
  location?: {                    // Geographic location
    city?: string;
    country?: string;
    coordinates?: {
      lat: number;
      lng: number;
    };
  };
}

Example Request Body

{
  "name": "TechCorp Solutions",
  "description": "Leading software development company specializing in AI and blockchain solutions",
  "website": "https://techcorp.example.com",
  "email": "contact@techcorp.example.com",
  "phone": "+380123456789",
  "address": "123 Innovation Street, Kyiv, Ukraine",
  "category": "Software Development",
  "tags": ["AI", "Blockchain", "Web Development", "Mobile Apps"],
  "visibility": "public",
  "logo": "https://storage.example.com/logos/techcorp.png",
  "socialLinks": {
    "linkedin": "https://linkedin.com/company/techcorp",
    "twitter": "https://twitter.com/techcorp",
    "github": "https://github.com/techcorp"
  },
  "foundedYear": 2020,
  "employeeCount": "11-50",
  "industry": "Information Technology",
  "location": {
    "city": "Kyiv",
    "country": "Ukraine",
    "coordinates": {
      "lat": 50.4501,
      "lng": 30.5234
    }
  }
}

Response Format

Success Response (201 Created)

{
  "id": "entity_123456789",
  "name": "TechCorp Solutions",
  "description": "Leading software development company specializing in AI and blockchain solutions",
  "website": "https://techcorp.example.com",
  "email": "contact@techcorp.example.com",
  "phone": "+380123456789",
  "address": "123 Innovation Street, Kyiv, Ukraine",
  "category": "Software Development",
  "tags": ["AI", "Blockchain", "Web Development", "Mobile Apps"],
  "visibility": "public",
  "logo": "https://storage.example.com/logos/techcorp.png",
  "socialLinks": {
    "linkedin": "https://linkedin.com/company/techcorp",
    "twitter": "https://twitter.com/techcorp",
    "github": "https://github.com/techcorp"
  },
  "foundedYear": 2020,
  "employeeCount": "11-50",
  "industry": "Information Technology",
  "location": {
    "city": "Kyiv",
    "country": "Ukraine",
    "coordinates": {
      "lat": 50.4501,
      "lng": 30.5234
    }
  },
  "onlineStatus": "offline",
  "lastOnline": null,
  "createdAt": "2025-01-14T17:10:00Z",
  "updatedAt": "2025-01-14T17:10:00Z",
  "createdBy": "user_987654321"
}

Error Responses

400 Bad Request

{
  "error": "Invalid JSON format"
}

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

{
  "error": "Only ADMIN or CONFIDENTIAL users can create confidential entities"
}

500 Internal Server Error

{
  "error": "Failed to create entity: Internal Server Error"
}

Code Examples

JavaScript/TypeScript

async function createEntity(entityData: CreateEntityRequest): Promise<Entity> {
  const response = await fetch('/api/entities/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(entityData)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || 'Failed to create entity');
  }

  return response.json();
}

// Usage example
const newEntity = await createEntity({
  name: "TechCorp Solutions",
  description: "Leading software development company",
  category: "Software Development",
  visibility: "public",
  website: "https://techcorp.example.com"
});

React Hook Example

import { useState } from 'react';

function useCreateEntity() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const createEntity = async (entityData: CreateEntityRequest) => {
    setLoading(true);
    setError(null);

    try {
      const response = await fetch('/api/entities/create', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(entityData),
      });

      if (!response.ok) {
        const errorData = await response.json();
        throw new Error(errorData.error);
      }

      const newEntity = await response.json();
      return newEntity;
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Unknown error');
      throw err;
    } finally {
      setLoading(false);
    }
  };

  return { createEntity, loading, error };
}

cURL Example

curl -X POST https://ring.ck.ua/api/entities/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "TechCorp Solutions",
    "description": "Leading software development company",
    "category": "Software Development",
    "visibility": "public",
    "website": "https://techcorp.example.com",
    "email": "contact@techcorp.example.com",
    "tags": ["AI", "Blockchain", "Web Development"]
  }'

Validation Rules

Required Fields

• name: Must be 1-100 characters
• category: Must be a valid category
• visibility: Must be 'public', 'member', or 'confidential'

Optional Field Constraints

• description: Maximum 1000 characters
• website: Must be a valid URL format
• email: Must be a valid email format
• phone: Must be a valid phone number format
• tags: Maximum 10 tags, each 1-50 characters
• foundedYear: Must be between 1800 and current year
• employeeCount: Must be one of predefined ranges

Security Considerations

1. Role-Based Access: Users can only create entities with visibility levels appropriate to their role
2. Input Validation: All input is validated and sanitized
3. Rate Limiting: Prevents abuse with 60 requests per minute limit
4. Audit Logging: All entity creation events are logged for security monitoring

Business Logic

1. Automatic Fields: id, onlineStatus, lastOnline, createdAt, updatedAt, and createdBy are automatically generated
2. Visibility Control: Confidential entities require ADMIN or CONFIDENTIAL role
3. Duplicate Prevention: System checks for duplicate entities based on name and email
4. Search Indexing: Created entities are automatically indexed for search functionality

Testing Examples

Unit Test Example

describe('POST /api/entities/create', () => {
  it('should create entity successfully with valid data', async () => {
    const entityData = {
      name: 'Test Entity',
      category: 'Technology',
      visibility: 'public'
    };

    const response = await request(app)
      .post('/api/entities/create')
      .set('Authorization', `Bearer ${validToken}`)
      .send(entityData)
      .expect(201);

    expect(response.body).toHaveProperty('id');
    expect(response.body.name).toBe('Test Entity');
  });

  it('should return 401 for unauthenticated requests', async () => {
    const response = await request(app)
      .post('/api/entities/create')
      .send({ name: 'Test' })
      .expect(401);

    expect(response.body.error).toBe('Unauthorized');
  });
});

Related Endpoints

• Get Entity by ID - Retrieve entity details
• Update Entity - Modify existing entity
• Delete Entity - Remove entity
• List Entities - Browse all entities
• Upload Entity Files - Attach files to entity

Changelog

• v1.0.0 - Initial implementation with basic entity creation
• v1.1.0 - Added social links and location support
• v1.2.0 - Enhanced validation and error handling
• v1.3.0 - Added confidential entity support