<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">

    <!-- GET endpoint: fetch dispatch status -->
    <route url="/V1/caz-dispatch/order/:orderId" method="GET">
        <service class="CodeAtoZDispatchApiDispatchStatusInterface" method="getByOrderId"/>
        <resources>
            <resource ref="CodeAtoZ_Dispatch::dispatch_read"/>
        </resources>
    </route>

    <!-- POST endpoint: update dispatch status -->
    <route url="/V1/caz-dispatch/order/:orderId/status" method="POST">
        <service class="CodeAtoZDispatchApiDispatchStatusInterface" method="updateStatus"/>
        <resources>
            <resource ref="CodeAtoZ_Dispatch::dispatch_write"/>
        </resources>
    </route>

</routes>

<?php
namespace CodeAtoZDispatchApi;

interface DispatchStatusInterface
{
    /**
     * Get dispatch status for an order.
     *
     * @param int $orderId
     * @return CodeAtoZDispatchApiDataDispatchStatusInterface
     * @throws MagentoFrameworkExceptionNoSuchEntityException
     */
    public function getByOrderId( int $orderId ): CodeAtoZDispatchApiDataDispatchStatusInterface;

    /**
     * Update dispatch status for an order.
     *
     * @param int $orderId
     * @param CodeAtoZDispatchApiDataDispatchUpdateInterface $update
     * @return bool
     * @throws MagentoFrameworkExceptionLocalizedException
     */
    public function updateStatus(
        int $orderId,
        CodeAtoZDispatchApiDataDispatchUpdateInterface $update
    ): bool;
}

<?php
namespace CodeAtoZDispatchApiData;

interface DispatchStatusInterface
{
    public const ORDER_ID      = 'order_id';
    public const STATUS        = 'status';
    public const UPDATED_AT    = 'updated_at';

    public function getOrderId(): int;
    public function getStatus(): string;
    public function getUpdatedAt(): string;

    public function setOrderId( int $orderId ): self;
    public function setStatus( string $status ): self;
    public function setUpdatedAt( string $updatedAt ): self;
}

<?php
namespace CodeAtoZDispatchModel;

use CodeAtoZDispatchApiDispatchStatusInterface;
use CodeAtoZDispatchApiDataDispatchStatusInterfaceFactory;
use CodeAtoZDispatchApiDataDispatchUpdateInterface;
use MagentoFrameworkExceptionNoSuchEntityException;
use MagentoFrameworkExceptionLocalizedException;
use MagentoSalesApiOrderRepositoryInterface;

class DispatchStatusRepository implements DispatchStatusInterface
{
    public function __construct(
        private readonly OrderRepositoryInterface $orderRepo,
        private readonly DispatchStatusInterfaceFactory $statusFactory,
        private readonly CodeAtoZDispatchModelResourceModelDispatchStatus $resource
    ) {}

    public function getByOrderId( int $orderId ): CodeAtoZDispatchApiDataDispatchStatusInterface
    {
        // Validate order exists — Magento 2 REST API custom endpoint best practice
        try {
            $this->orderRepo->get( $orderId );
        } catch ( Exception $e ) {
            throw new NoSuchEntityException( __( 'Order %1 not found.', $orderId ) );
        }

        $status = $this->statusFactory->create();
        $this->resource->load( $status, $orderId, 'order_id' );

        if ( ! $status->getId() ) {
            throw new NoSuchEntityException( __( 'No dispatch status for order %1.', $orderId ) );
        }

        return $status;
    }

    public function updateStatus( int $orderId, DispatchUpdateInterface $update ): bool
    {
        if ( ! in_array( $update->getStatus(), ['pending','dispatched','delivered'], true ) ) {
            throw new LocalizedException( __( 'Invalid status value for Magento 2 REST API custom endpoint.' ) );
        }

        $status = $this->statusFactory->create();
        $this->resource->load( $status, $orderId, 'order_id' );
        $status->setData([
            'order_id'   => $orderId,
            'status'     => $update->getStatus(),
            'updated_at' => date( 'Y-m-d H:i:s' ),
        ]);
        $this->resource->save( $status );
        return true;
    }
}

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

    <!-- Bind interface to implementation for Magento 2 REST API custom endpoint -->
    <preference for="CodeAtoZDispatchApiDispatchStatusInterface"
                type="CodeAtoZDispatchModelDispatchStatusRepository"/>

    <preference for="CodeAtoZDispatchApiDataDispatchStatusInterface"
                type="CodeAtoZDispatchModelDispatchStatus"/>

    <preference for="CodeAtoZDispatchApiDataDispatchUpdateInterface"
                type="CodeAtoZDispatchModelDispatchUpdate"/>

</config>