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;