Entity API OData – BijouCore Docs

📄 Overview

BijouCore automatically generates OData v4 compliant REST APIs for all entities defined in the system. These APIs provide standardized access to create, read, update, and delete entity records with advanced querying capabilities.

All entity endpoints follow the pattern: /$odata/{EntityName}

🔍 Basic Operations

GET - Retrieve Records

// Get all records
GET /$odata/Customer

// Get single record by ID
GET /$odata/Customer('123e4567-e89b-12d3-a456-426614174000')

// Get with selected fields
GET /$odata/Customer?$select=Name,Email,CreatedAt

// Get with filtering
GET /$odata/Customer?$filter=IsActive eq true

// Get with sorting
GET /$odata/Customer?$orderby=Name desc

// Get with pagination
GET /$odata/Customer?$top=20&$skip=40

POST - Create Record

POST /$odata/Customer
Content-Type: application/json

{
  "Name": "John Doe",
  "Email": "john@example.com",
  "IsActive": true
}

PUT - Update Record

PUT /$odata/Customer('123e4567-e89b-12d3-a456-426614174000')
Content-Type: application/json

{
  "Name": "John Smith",
  "Email": "john.smith@example.com",
  "IsActive": true
}

DELETE - Remove Record

DELETE /$odata/Customer('123e4567-e89b-12d3-a456-426614174000')

🏷️ Annotations API

Annotations provide a flexible tagging system for entity records. Each entity supports annotation operations through dedicated endpoints.

Retrieving Annotations

// Annotations are automatically included in all entity responses
GET /$odata/Customer('123e4567-e89b-12d3-a456-426614174000')

// Response always includes the $Annotations field:
{
  "Id": "123e4567-e89b-12d3-a456-426614174000",
  "Name": "John Doe",
  // ... other fields ...
  "$Annotations": [
    {
      "Id": "annotation-id",
      "Type": "type-id",
      "Subject": "Important customer",
      "Text": null,
      "CreatedAt": "2024-01-15T10:30:00Z",
      "CreatedBy": "user-id"
    }
  ]
}

Creating Annotations

POST /$odata/Customer/123e4567-e89b-12d3-a456-426614174000/annotations
Content-Type: application/json

{
  "TypeId": "annotation-type-id",
  "Subject": "VIP Customer",
  "Text": null  // Optional longer description
}

Updating Annotations

PUT /$odata/Customer/123e4567-e89b-12d3-a456-426614174000/annotations/annotation-id
Content-Type: application/json

{
  "Subject": "Updated VIP Status",
  "Text": "Customer upgraded to platinum tier"
}

Deleting Annotations

DELETE /$odata/Customer/123e4567-e89b-12d3-a456-426614174000/annotations/annotation-id

🔗 Expanding Relations

Use the $expand query option to include related entity data in a single request.

// Expand single relation
GET /$odata/Order?$expand=Customer

// Expand multiple relations
GET /$odata/Order?$expand=Customer,OrderItems

// Nested expansion
GET /$odata/Order?$expand=OrderItems($expand=Product)

// Expand with filtering
GET /$odata/Order?$expand=OrderItems($filter=Quantity gt 5)

⚡ Advanced Queries

Filter Operations

Operator	Description	Example
eq	Equal	`$filter=Name eq 'John'`
ne	Not equal	`$filter=Status ne 'Inactive'`
gt	Greater than	`$filter=Amount gt 100`
lt	Less than	`$filter=CreatedAt lt 2024-01-01`
ge	Greater than or equal	`$filter=Quantity ge 10`
le	Less than or equal	`$filter=Price le 50.00`
contains	String contains	`$filter=contains(Name, 'Smith')`
startswith	String starts with	`$filter=startswith(Code, 'PRD')`
endswith	String ends with	`$filter=endswith(Email, '.com')`

Combining Filters

// AND condition
GET /$odata/Product?$filter=IsActive eq true and Price gt 10

// OR condition
GET /$odata/Customer?$filter=City eq 'New York' or City eq 'Los Angeles'

// Complex conditions
GET /$odata/Order?$filter=(Status eq 'Pending' or Status eq 'Processing') and Total gt 1000

🔒 Security

All OData endpoints respect the entity security permissions configured in the system:

Read permission required for GET operations
Write permission required for POST, PUT, and DELETE operations
Field-level security is enforced for sensitive data
Annotation operations follow the parent entity's permissions