Operations¶

T3api is based on operations. Operation in fact is an API endpoint, which allows to access resources. There are two types of operations: collection and item. As you can guess, collection operation returns multiple items of resource and item operation returns single item (fetched by specified id).

Configuring operations¶

To configure operation for resource you need to pass collectionOperations or itemOperations parameters into ApiResource annotation as on example below. Don’t bother about the key of the operation for now. In our example we use get, but you could use there any other string. The important part is the path. This is the URL path for the endpoint, prefixed by the basePath from route enhancer (see more on route-enhancer).

Path of the item operation needs to contain {id} parameter. This parameter is replaced by uid of the entity when fetching single item.

Important

Path to API endpoints is prefixed by the default language base path. For example: If your default language base path is en then endpoint URL will be: /en/_api/*.

use SourceBroker\T3api\Annotation\ApiResource;

/**
 * @ApiResource(
 *     collectionOperations={
 *          "get"={
 *              "path"="/items",
 *          },
 *     },
 *     itemOperations={
 *          "get"={
 *              "path"="/items/{id}",
 *          }
 *     },
 * )
 */
class Item extends \TYPO3\CMS\Extbase\DomainObject\AbstractEntity
{
}

Note

You can determine multiple operations of each type for every property, but keep in mind that first collection operation and first item operation are treated as the main operations. It means that:

The path of the first collection operation is used in the main endpoint.
The path of the first item operation is used to define resource IRI (@id property).

Supported operation methods¶

T3api supports all REST methods

HTTP Method	Operation type	Example URL	Purpose
GET	Collection	/resource	Reading collection of the items
GET	Item	/resource/{id}	Reading single item
POST	Collection	/resource	Creating new item
PATCH	Item	/resource/{id}	Updating the item
PUT	Item	/resource/{id}	Replacing the item
DELETE	Item	/resource/{id}	Deleting the item

Important

Notice that POST operation is a type of collection operations

Response of GET collection operation¶

As mentioned in Getting started T3api uses Hydra Core Vocabulary. That’s why collection response of GET method is enriched by some additional properties:

hydra:member - contains array of matched entities.
hydra:totalItems - contains number of all items.
hydra:view - contains data useful for pagination (see more on Pagination).
hydra:search - contains data useful for filtering (see more on Filtering).

Here is an example of basic response for collection operation.

{
  "hydra:member": [
    {
      "@id": "/_api/news/news/1",
      "uid": 1,
      "title": "Lorem ipsum dolor sit amet enim",
      "teaser": "Pellentesque facilisis. Nulla imperdiet sit amet magna.",
      "datetime": "2019-08-30T07:30:00+00:00"
    },
    {
      "@id": "/_api/news/news/2",
      "uid": 2,
      "title": "Lorem ipsum dolor sit amet enim",
      "teaser": "Aliquam erat ac ipsum. Integer aliquam purus",
      "datetime": "2019-08-30T07:30:00+00:00"
    }
  ],
  "hydra:totalItems": 2,
  "hydra:view": {
      "hydra:first": "/_api/users?itemsPerPage=50&page=1",
      "hydra:last": "/_api/users?itemsPerPage=50&page=5",
      "hydra:next": "/_api/users?itemsPerPage=50&page=2",
      "hydra:pages": [
          "/_api/users?itemsPerPage=50&page=1",
          "/_api/users?itemsPerPage=50&page=2",
          "/_api/users?itemsPerPage=50&page=3",
          "/_api/users?itemsPerPage=50&page=4",
          "/_api/users?itemsPerPage=50&page=5"
      ],
      "hydra:page": 1
  }
}

Item operation response¶

In response of all item operations only object is received. Response does not contain any additional attributes because they are useless in single item operation context.

{
  "@id": "/_api/news/news/1",
  "uid": 1,
  "title": "Lorem ipsum dolor sit amet enim",
  "teaser": "Pellentesque facilisis. Nulla imperdiet sit amet magna.",
  "datetime": "2019-08-30T07:30:00+00:00",
  "bodytext": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>",
}

Customizing returned properties¶

By default all properties of entities are returned. That may not be expected behavior because of performance and security reasons. You can easily manage properties returned from any endpoint using serialization context groups.

Main endpoint¶

There is one special build-in endpoint which is not determined by @ApiResource annotation - Main endpoint. It contains list all available collection operations. It is useful for creating Postman requests collections or for frontend applications which avoids to use hardcoded path for the endpoints. Main endpoint is available under base path (default https://example.com/_api/). Example response on the main endpoint may looks as one below:

{
  "resources": {
    "SourceBroker\\T3apinews\\Domain\\Model\\Category": "/_api/news/categories",
    "SourceBroker\\T3apinews\\Domain\\Model\\File": "/_api/news/files",
    "SourceBroker\\T3apinews\\Domain\\Model\\News": "/_api/news/news",
    "SourceBroker\\T3apinews\\Domain\\Model\\Tag": "/_api/news/tags"
  }
}

Class used as a response in main endpoint may be overwritten in ext_localconf.php:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['t3api']['mainEndpointResponseClass'] = \Vendor\Ext\MyCustomMainEndpoint::class;

To disable main endpoint it is just needed to set mainEndpointResponseClass to null. It will result in 404 error response.

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['t3api']['mainEndpointResponseClass'] = null;