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): void
       {
           /** @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): void
    {
        /** @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 }