Tutorial: Building a Simple API with DataForge

This tutorial demonstrates how to create a simple, powerful API using DataForge. We will create an API endpoint to fetch invoice data, covering both the setup and implementation process.

---

Prerequisites

Before we begin, ensure that:

• DataForge is installed and configured in your Laravel project. Refer to the installation guide.
• You have basic knowledge of Laravel and PHP.

---

Step 1: Define an SQL Class

We need to define the SQL class responsible for querying invoice data.

File Location:

app/DataForge/Sql/Invoice.php

Example SQL Class:

namespace App\DataForge\Sql;

use DataForge\Sql;

class Invoice extends Sql
{
    public function list(array &$data)
    {
        $query = Query('InvoiceList');

        $query->select('list', 'i.id AS invoiceId, i.customer_id AS customerId, i.total AS totalAmount, i.status AS status');
        $query->from('invoices AS i');
        $query->filter('i.status = {request.status}');
        $query->filterOptional('i.customer_id = {request.customerId}');
        $query->filterAnyOneRequired('CustomerOrStatus', [
            'i.customer_id = {request.customerId}',
            'i.status = {request.status}'
        ]);
        $query->order('{request.sort}', '{request.order}');

        return $query;
    }
}

---

Step 2: Define an API Endpoint

We’ll use the preconfigured api/list endpoint to fetch paginated invoice data.

Sample Request:

GET /api/list/Invoice/list?status=paid&pageNo=1&limit=10

Sample Response:

{
    "total": 50,
    "items": [
        {
            "invoiceId": 12345,
            "customerId": 67890,
            "totalAmount": 500.00,
            "status": "paid"
        },
        ...
    ]
}

---

Step 3: Define an Entity Class

The Entity class encapsulates the logic for invoice-specific attributes and relationships.

File Location:

app/DataForge/Entity/Invoice.php

Example Entity Class:

namespace App\DataForge\Entity;

use DataForge\Entity;

class Invoice extends Entity
{
    public function init($id)
    {
        return \Sql('Invoice:list', ['id' => $id, 'select' => 'item'])->fetchRow();
    }

    public function getCustomer()
    {
        return DataForge::getCustomer($this->customer_id);
    }

    public function getTotalAmount(): float
    {
        return (float) $this->totalAmount;
    }
}

---

Step 4: Combine Logic in a Task Class

Define a Task class to handle custom workflows. For this example, we will fetch invoice details along with customer information.

File Location:

app/DataForge/Task/InvoiceTask.php

Example Task Class:

namespace App\DataForge\Task;

use DataForge\Task;

class InvoiceTask extends Task
{
    public function detail($request)
    {
        $id = $request->get('invoiceId');
        if (!$id) {
            $this->setError('Invoice ID is missing!');
            return false;
        }

        $invoice = DataForge::getInvoice($id);
        if (!$invoice) {
            $this->setError('Invoice not found!');
            return false;
        }

        return [
            'Invoice' => $invoice->toArray(),
            'Customer' => $invoice->Customer->toArray()
        ];
    }
}

---

Step 5: Test the API

Sample Request:

GET /api/Task/InvoiceTask/detail?invoiceId=12345

Sample Response:

{
    "Invoice": {
        "id": 12345,
        "customerId": 67890,
        "totalAmount": 500.00,
        "status": "paid"
    },
    "Customer": {
        "id": 67890,
        "name": "John Doe",
        "email": "john.doe@example.com"
    }
}

---

Conclusion

Congratulations! You’ve successfully created a simple API using DataForge. This demonstrates how SQL, Entity, and Task classes work together to deliver scalable and maintainable APIs. For advanced use cases, explore the full API reference.