API Endpoints

Overview

The DataForge package provides 7 powerful API endpoints to handle various web service requirements. These endpoints cover data retrieval, manipulation, and integration needs, making them suitable for applications ranging from small-scale systems to enterprise-grade platforms.

1. `api/list`

Description:
Fetches a paginated list of records from a specified SQL class and method.

Endpoint Format:

/api/list/{sql_class_name}/{sql_class_method}?select={select_type}&pageNo={page_number}&limit={record_limit}&keyword={search_keyword}&sort={sort_field}&order={sort_order}

Key Features:

Supports pagination using pageNo and limit.
Provides total count of matched records.
Applies dynamic filters and sorting.

Sample Request:

/api/list/Property/list?keyword=test&pageNo=2&limit=20&sort=id&order=desc

Sample Response:

{
  "total": 256,
  "items": [
    {"propertyId": 1234, "address1": "1 xxx street", "address2": "", "suburb": "yyyyyy", "state": "WWW", "postcode": 1234},
    ...
  ]
}

2. `api/all`

Description:
Fetches all matched records from a specified SQL class and method. Similar to api/list but without pagination.

Endpoint Format:

/api/all/{sql_class_name}/{sql_class_method}?select={select_type}&limit={record_limit}&keyword={search_keyword}

Key Features:

Fetches all or limited records using the limit parameter.
Ideal for dropdowns and complete lists.

Sample Request:

/api/all/Property/list?keyword=test

Sample Response:

[
  {"propertyId": 1234, "address1": "1 xxx street", "address2": "", "suburb": "yyyyyy", "state": "WWW", "postcode": 1234},
  ...
]

3. `api/item`

Description:
Fetches the first matched record from a specified SQL class and method.

Endpoint Format:

/api/item/{sql_class_name}/{sql_class_method}?select={select_type}&keyword={search_keyword}

Key Features:

Returns a single record as a JSON object.
Supports filters similar to api/list.

Sample Request:

/api/item/Property/list?keyword=test

Sample Response:

{
  "propertyId": 1234,
  "address1": "1 xxx street",
  "address2": "",
  "suburb": "yyyyyy",
  "state": "WWW",
  "postcode": 1234
}

4. `api/field`

Description:
Fetches the first column value from the first matched record of a specified SQL class and method.

Endpoint Format:

/api/field/{sql_class_name}/{sql_class_method}?select={select_type}&keyword={search_keyword}

Key Features:

Ideal for fetching single values (e.g., totals, sums, or aggregates).

Sample Request:

/api/field/Property/list?keyword=test

Sample Response:

5. `api/entity`

Description:
Fetches an entity's base properties, relationships, or grouped attributes.

Endpoint Format:

/api/entity/{entity_name}/{id}?attrib={attribute_name}&attribGroup={group_name}&skipBaseAttrib={0|1}

Key Features:

Retrieves entity base properties (via init method).
Supports lazy-loaded attributes and attribute groups.
Optionally skips base attributes.

Sample Requests:

Fetch base properties:
```
/api/entity/Tenant/1976
```
Fetch with related attribute:
```
/api/entity/Tenant/1976?attrib=Property
```

Fetch with attribute group:

/api/entity/Tenant/1976?attribGroup=FinancialSummary&skipBaseAttrib=1

Sample Response:

{
  "Tenant": {
    "id": 1234,
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  "Property": {
    "propertyId": 1436,
    "address1": "45 xxx street",
    ...
  }
}

6. `api/Task`

Description:
Executes Task methods for custom actions like Save, Update, Delete, or complex data preparation.

Endpoint Format:

/api/Task/{Task class name}/{Task Method}

Key Features:

Combines SQL and Entity operations for complex workflows.
Handles custom actions beyond standard CRUD.

Sample Request:

/api/Task/Tenant/detail?tenantId=1234

Sample Response:

{
  "Tenant": { "id": 1234, "firstName": "John" },
  "PropertyAddress": "123 Main St",
  "Permissions": ["view", "edit"],
  "FinancialInfo": {
    "RentPaid": 5200.00,
    "InvoicePaid": 2089.25
  }
}

7. `api/GuestTask`

Description:
Allows unauthenticated access to Task methods with a guest prefix in their names.

Endpoint Format:

/api/GuestTask/{Task class name}/{Task Method}

Key Features:

Provides limited access for guest users.
Ensures sensitive data remains secure.

Sample Request:

/api/GuestTask/Tenant/guestDetail?tenantId=1234

Sample Response:

{
  "Tenant": { "id": 1234, "firstName": "John" },
  "PropertyAddress": "123 Main St"
}

Key Strengths

1. Versatility

Covers diverse use cases: pagination (api/list), full data retrieval (api/all), single records (api/item), aggregates (api/field), and workflows (api/Task, api/GuestTask).

2. Scalability

Efficient for small to large-scale applications.
Modular Task and Entity methods ensure seamless expansion.

3. Flexibility

Customizable filters, sorting, and workflows.
Easily integrates with various frontends or third-party services.

4. Security

Clear distinction between authenticated and guest endpoints.
Controlled data exposure with api/GuestTask.

5. Performance Optimization

Lazy loading of entity attributes.
Dynamic filtering minimizes data overhead.

Conclusion

These 7 endpoints form a comprehensive framework for handling diverse data needs, ensuring a balance of performance, flexibility, and security. Perfect for creating scalable and maintainable web services, DataForge’s endpoints simplify development without compromising functionality.