magento 2.4.2 add custom attribute in order api only

Question

On my magento, I've created a custom attribute for the order and a custom attribute for the order items. In order to show these on the order api, I've placed my two attributes in an extension_attributes.xml and added the relative plugins for the OrderInterface and the OrderItemInterface. This modification works: if I call the orders api, I can see my two attributes in the relative extension_attributes key.

Now I'd like to summarize these two values in only one key called "description". This new key should not be present in the order object but only in the order api.

So my questions are:

• is there a way to add a key to the order api without creating the corresponding field in the order object?
• is there a way for the description key to be outside the "extension_attributes"?

Basically, my json should look something like this:

{
    "base_currency_code": "USD",
    "base_discount_amount": 0,
    "base_grand_total": 1994.43,
    .... // all the other order information
    "description": "..." // this is where the new key is supposed to go instead of being  inside the extension_attributes key
 }

Answer 1

As we know, Magento 2 implements the "service contracts" design pattern, which consists of both service and data interfaces. These interfaces hides business logic from service requestors like controllers, web services, and other modules.

Magento 2 APIs are bound to service contracts via configuration files.

vendor/magento/module-sales/etc/di.xml

<preference for="Magento\Sales\Api\Data\OrderInterface" type="Magento\Sales\Model\Order"/>

vendor/magento/module-sales/Api/OrderRepositoryInterface.php

interface OrderRepositoryInterface
{
    /**
     * @param int $id The order ID.
     * @return \Magento\Sales\Api\Data\OrderInterface Order interface.
     */
    public function get($id);
}

The API Data interfaces strictly define the data set available for data object for the entity, return types etc.

vendor/magento/module-sales/Api/Data/OrderInterface.php

/*
 * Increment ID.
 */
const INCREMENT_ID = 'increment_id';

/**
 * Gets the increment ID for the order.
 *
 * @return string|null Increment ID.
 */
public function getIncrementId();

/**
 * Sets the increment ID for the order.
 *
 * @param string $id
 * @return $this
 */
public function setIncrementId($id);

When it comes to web API, the data interface represents the data to be included in the response. So 3rd party developers cannot change API data interfaces in the Magento core.

The only way to add custom data to these data interfaces is to use extension attributes. In that case, data object to be extended must also implement the Magento\Framework\Api\ExtensibleDataInterface interface.

vendor/magento/module-sales/Api/Data/OrderInterface.php

interface OrderInterface extends \Magento\Framework\Api\ExtensibleDataInterface
{
    ..
}