Important

You are browsing documentation for version 5.0 of OroCommerce, OroCRM, and OroPlatform, maintained until August 2024 and supported until March 2026. See version 5.1 (the latest LTS version) of the Oro documentation for information on latest features.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Headers

For some types of REST API requests, you can retrieve additional information like the total number of records, the number of affected records, etc. To do this, use the X-Include request header. The value of this header should contain keys separated by a semicolon (;).

The following example shows how to get the total number of accounts:

curl "http://orocrm.loc/index_dev.php/api/accounts?page=1&limit=2" -v --header="X-Include:totalCount" --header="X-WSSE:..."

The corresponding response:

< HTTP/1.1 200 OK
...
< X-Include-Total-Count: 67
...

Hint

To generate a WSSE header, run: php bin/console oro:wsse:generate-header YOUR_API_KEY.

Existing X-Include Keys

The following table describes all existing keys for the X-Include header.

Request Type	X-Include key	Response Header	Description
all	noHateoas	–	Removes all HATEOAS-related links from the response.
get a list of entities	totalCount	X-Include-Total-Count	Returns the total number of entities. It is calculated based on input filters.
delete a list of entities	totalCount	X-Include-Total-Count	Returns the total number of entities. It is calculated based on input filters.
delete a list of entities	deletedCount	X-Include-Deleted-Count	Returns the number of deleted entities

Add New X-Include Key

To add a custom key to the X-Include header:

1. Create a processor to handle your key:

   namespace Oro\Bundle\ApiBundle\Processor\DeleteList;
   
   use Oro\Component\ChainProcessor\ContextInterface;
   use Oro\Component\ChainProcessor\ProcessorInterface;
   use Oro\Bundle\ApiBundle\Processor\Context;
   
   /**
    * Calculates and sets the total number of deleted records to the "X-Include-Deleted-Count" response header,
    * in case it was requested by the "X-Include: deletedCount" request header.
    */
   class SetDeletedCountHeader implements ProcessorInterface
   {
       public const RESPONSE_HEADER_NAME = 'X-Include-Deleted-Count';
       public const REQUEST_HEADER_VALUE = 'deletedCount';
   
       /**
        * {@inheritdoc}
        */
       public function process(ContextInterface $context)
       {
           /** @var DeleteListContext $context */
   
           if ($context->getResponseHeaders()->has(self::RESPONSE_HEADER_NAME)) {
               // the deleted records count header is already set
               return;
           }
   
           $xInclude = $context->getRequestHeaders()->get(Context::INCLUDE_HEADER);
           if (empty($xInclude) || !in_array(self::REQUEST_HEADER_VALUE, $xInclude, true)) {
               // the deleted records count is not requested
               return;
           }
   
           $result = $context->getResult();
           if (null !== $result && is_array($result)) {
               $context->getResponseHeaders()->set(self::RESPONSE_HEADER_NAME, count($result));
           }
       }
   }
   

   oro_api.delete_list.set_deleted_count_header:
       class: Oro\Bundle\ApiBundle\Processor\DeleteList\SetDeletedCountHeader
       tags:
           - { name: oro.api.processor, action: delete_list, group: delete_data, priority: -10 }
   

2. Create a processor to remove your response header when an error occurs:

namespace Oro\Bundle\ApiBundle\Processor\DeleteList;

use Oro\Component\ChainProcessor\ContextInterface;
use Oro\Component\ChainProcessor\ProcessorInterface;

/**
 * Removes the "X-Include-Deleted-Count" response header if any error occurs.
 */
class RemoveDeletedCountHeader implements ProcessorInterface
{
    /**
     * {@inheritdoc}
     */
    public function process(ContextInterface $context)
    {
        /** @var DeleteListContext $context */

        if ($context->hasErrors()
            && $context->getResponseHeaders()->has(SetDeletedCountHeader::RESPONSE_HEADER_NAME)
        ) {
            $context->getResponseHeaders()->remove(SetDeletedCountHeader::RESPONSE_HEADER_NAME);
        }
    }
}

oro_api.delete_list.remove_deleted_count_header:
    class: Oro\Bundle\ApiBundle\Processor\DeleteList\RemoveDeletedCountHeader
    tags:
        - { name: oro.api.processor, action: delete_list, group: normalize_result, priority: 100 }