| Extension Key: | expose |
|---|---|
| Language: | en |
| Keywords: | webservice, extbase, xml, json |
| Author: | Dominique Feyer <dfeyer@ttree.ch> for ttree ltd |
| Date: | 2012-04-13 |
| Version: | 0.1.0 |
| Description: | This is the documentation for the TYPO3 extension expose. Expose extension allow easy setup of readonly web services, configured by TypoScript. |
Contents
This extension provide a simple way to configured how you will expose your Extbase domain model as a standard readonly webservice.
Currently only XML is supported but a JSON and YAML view is planned.
You can configure with properties will be exported in TypoScript.
As Github don't support the all the Restructured Text element used by TYPO3 Documentation Team, please check the RAW README.rst to have proper documentation.
You need to extension the controller abstract class Tx_Expose_MVC_Controller_BasicController, like in this example:
class Tx_Extension_Controller_RecordApiController extends Tx_Expose_MVC_Controller_BasicController {
/**
* @var Tx_Extension_Domain_Repository_RecordRepository
*/
protected $recordRepository;
/**
* @param Tx_Extension_Domain_Repository_RecordRepository $recordRepository
* @return void
*/
public function injectFilmRepository(Tx_Extension_Domain_Repository_RecordRepository $recordRepository) {
$this->recordRepository = $recordRepository;
}
/**
* @return void
*/
public function listAction() {
$records = $this->recordRepository->findAll();
$this->view->setRootElementName('records');
$this->view->assign('record', $records);
}
}By default the XML view is selected. The root element name can be set with $this->view->setRootElementName($name). To respect RESTful philisophy, you can assign only one variable per action. In this case every domain model in the $records variable will be rendered in a node name "record".
You can include your plugin with the TypoScript configuration:
Example:
lib.api.records = USER
lib.api.records {
userFunc = tx_extbase_core_bootstrap->run
extensionName = Extension
pluginName = Api
switchableControllerActions {
RecordApi {
1 = list
2 = show
}
}
}
config {
absRefPrefix = http://www.domain.com/
debug = 0
# deactivate Standard-Header
disableAllHeaderCode = 1
# no xhtml tags
xhtml_cleaning = none
admPanel = 0
metaCharset = utf-8
# define charset
additionalHeaders = Content-Type:text/xml;charset=utf-8
disablePrefixComment = 1
}
page = PAGE
page.10 < lib.api.records
With this setup you can use the page cache, to cache the content of your webservice, if this is not what you need you can use a USER_INT.
Note
In a future version, we will integrate the Caching Framework to have a more configurable caching solution.
The administration of the webservice content is done entirely in TypoScript, here is an example of configuration:
Example:
plugin.tx_extension {
settings {
api {
conf {
# Configuration for rootElement "records"
records {
path = api.node.record
modelComment = Film Model
}
}
node {
record {
name {
path = name
element = completion_date
}
content {
path = content
element = content
userFunc {
class = EXT:extension/Classes/Utility/TextUtility.php:&Tx_Extension_Utility_TextUtility
method = cleanTextContent
}
}
country {
path = country.name
element = country_name
}
}
}
}
}
}
You can add stdWrap parsing with the key "stdWrap" in any node.
A node can be a Content Object element, with this kind of configuration:
Example:
plugin.tx_extension {
settings {
api {
conf {
# Configuration for rootElement "records"
records {
path = api.node.record
modelComment = Film Model
}
}
node {
record {
name {
path = name
element = completion_date
}
link = TEXT
link {
typolink {
parameter = 1261
additionalParams = &tx_extension_list[controller]=List&tx_extension_list[action]=show&tx_extension_list[film]={field:uid}
additionalParams.insertData = 1
returnLast = url
typolink.useCacheHash = 1
}
}
}
}
}
}
}
You can use the element type "relations" to include children element. Each relation element can have their proper configuration (see the conf, key). Currently we support only multiple relation, an example XML output can be:
Example:
<records>
<record>
<name>Name</name>
<groups>
<group>
<name>Group Name #1</name>
</group>
<group>
<name>Group Name #2</name>
</group>
</groups>
</record>
<record>
...
</record>
</records>
To support 1:1 relation you can use the type "relation" (without the ending "s"), like have this kind of output:
Example:
<records>
<record>
<name>Name</name>
<group>
<name>Group Name #1</name>
</group>
</record>
<record>
...
</record>
</records>
You can also include property from a 1:1 relation by setting path to "group.name", to have:
Example:
<records>
<record>
<name>Name</name>
<group_name>Group Name #1</group_name>
</record>
<record>
...
</record>
</records>
The extension support a basic token authentification. Authentification class can be override, and must implement the interface "Tx_Expose_Security_SecurityInterface" and trow "Tx_Expose_Exception_AccessException" if the access is not allowed.
With the Simple Token authentification you can create database stored "token", with a custom hash for each token. Has must be unique, but that's not checked automatically now (Implementation in progress). Each token can be part of a group, and you can configure in the TypoScript with group can access the current WebService.
Please don't use the security class without SSL enable on the webservice URL. Here a small exemple of the security class configuration:
Example:
plugin.tx_expose {
settings {
secure {
class = Tx_Expose_Security_SimpleTokenSecurity
configuration {
allowedGroups = 1
argumentName = token
}
}
}
}
The "argumentName" allow you to choose the arguement name in your plugin who store the token hash value.
- Add a security layer The first version will only support a sort of access key. The access key must be provided in the URL to access the service. More advanced security layer can be added later
- Support JSON and other format We can abstract the document creation stack to allow easy support of multiple format like JSON and YAML per example. If you need those formats, you can provide a patch or contact us
- Add support for CRUD operation Currently this not the use case of the extension, but maybe later we can allow CRUD operations on domain model.