TypoScript Setup

Configuring with TypoScript Setup

All of the following settings are configured at

plugin.tx_nnrestapi {
    settings {
        // ... HERE!
    }
}
Copied!

accessGroups

Property
accessGroups
Data type
array
Description
Allows the centralized definition of access groups to be used with the @Api\Access("config[name]") annotation.

Can be a comma separated list of users, see this section for more examples.

plugin.tx_nnrestapi.settings.accessGroups {

    // use @Api\Access("config[example1]")
    example1 = fe_users[3,2]

    // use @Api\Access("config[example2]")
    example1 = fe_users[david], fe_groups[1], ip_users[5.10]
}
Copied!
Default
no groups defined

apiController

Property
apiController
Data type
string
Description

Defines which Controller takes care of resolving the class and method that should be called. If you want to take complete control of the delegation logic, dependency injection etc., replace the default class with your own class.

Your class should extend the Nng\Nnrestapi\Controller\AbstractApiController. It will be instanciated by the PageResolver-MiddleWare Nng\Nnrestapi\Middleware\PageResolver which will call the indexAction in your class.

plugin.tx_nnrestapi.settings.apiController = My\Extension\Controller\ApiController
Copied!
Default
NngNnrestapiControllerApiController

allowedFileUploadSuffix

Property
allowedFileUploadSuffix
Data type
string
Description

Defines which suffixes are allowed for the file-upload. If nothing is set, it will fallback to the "safe" suffixes defined in EXT:nnhelpers

// define it globally for all configurations ...
plugin.tx_nnrestapi.settings {
   allowedFileUploadSuffix = jpg, png, svg
}

// or individually for a single configuration
plugin.tx_nnrestapi.settings.fileUploads {
   myUploadConfig {
        allowedFileUploadSuffix = jpg, bmp
   }
}
Copied!
Default
NngNnrestapiControllerApiController

fileUploads

Property
fileUploads
Data type
array
Description

Define upload-paths that can be used in the @Api\Upload("config[key]") annotation.

Read how to use this annotation or find out how to create a custom path resolver to dynamically set the upload path.

plugin.tx_nnrestapi.settings.fileUploads {

    // use @Api\Upload("config[myUploadConfig]") at your method
    myUploadConfig {

        // the path to use, if no other criteria below meet
        defaultStoragePath = 1:/myfolder/

        // optional: custom method to resolve the upload-path
        pathFinderClass = My\Extension\Helper\UploadPathHelper::getUploadPath

        // target-path for file, file-0, file-1, ... from multipart/form-data
        file = 1:/myfolder/files/

        // target-path for image, image-0, image-1, ... from multipart/form-data
        image = 1:/myfolder/images/
    }
}
Copied!
Default
NngNnrestapiControllerApiController

globalDistillers

Property
globalDistillers
Data type
array
Description

The main purpose of a "Distiller" is to reduce the amount of data returned to the frontend by removing certain field from a model after it is converted to a JSON.

This can be done on a per-method basis or globally for a certain Model type by setting the globalDistillers in the TypoScript.

Find out how to use global distillers.

plugin.tx_nnrestapi.settings.globalDistillers {

    // use the model class name as a key here
    My\Extension\Domain\Model\Name {
        
        // "exclude" will keep all fields EXCEPT the ones listed here
        exclude = pid, other_field

        // "include" will remove ALL fields EXCEPT the ones listed here
        include = uid, title, bodytext

        // "flattenFileReferences" will reduce the FALs to their publicUrl
        flattenFileReferences = 1
    }
}
Copied!
Default
parent is excluded for TYPO3CMSExtbaseDomainModelCategory

insertDefaultValues

Property
insertDefaultValues
Data type
array
Description

Define default values to be set when a new model is created and passed to your endpoint.

This is very useful, when you are using dependency injection (DI) to automatically create a new Model in your POST-method as described in this section

Use-case would be: Every new entry created in the frontend should be inserted in a given SysFolder in the backend. This can be accomplished by setting a default pid for the model in the TypoScript:

These values will be overridden, if the frontend sets a value for the field.

plugin.tx_nnrestapi.settings.insertDefaultValues {

    // use the model-name as a key
    My\Extension\Domain\Model\Name {

        // define default value for a new model
        pid = 6

        // you can even set default SysCategories
        categories {
            0 = 1
            1 = 2
        }
    }
}
Copied!
Default
none defined

kickstarts

Property
kickstarts
Data type
array
Description

Allows adding templates to the kickstarter-examples.

These can be accessed in the "RestApi" backend module by clicking on the tab "Kickstarter".

Find out how to create your own templates for the Kickstarter and replace / customize variables in the templates during the download.

plugin.tx_nnrestapi.settings.kickstarts {
    myexample {

        // title and description for the list view
        title = A frontend in React
        description = Example React frontend application

        // icon-class (FontAwesome/Free supported)
        icon = fas fa-box

        // path can be a zip or a folder. Must be inside an EXT-folder or fileadmin!
        path = EXT:myextension/Resources/Private/Kickstarts/react.zip

        // list of texts to replace in source-codes
        replace {
            my/extname = [#vendor-lower#]/[#ext-lower#]
        }
    }
}
Copied!
Default
see TypoScript

localization

Property
localization
Data type
array
Description
Controls how to handle translations when retrieving data from the database.
By default, localization is NOT enabled. This can be changed by setting

enabled = 1.

While checking, which language was requested, the nnrestapi will evaluate the URL path (e.g. ../en/api/endpoint), the ?L=... parameter in the URL and the header sent by the frontend-application. Use languageHeader to define which headers of the request to take into consideration.

Read how localization is handled.

plugin.tx_nnrestapi.settings.localization {
    
    // enable the localization (default is 0 / off)
    enabled = 1

    // which headers to check for language requested by frontend
    languageHeader = x-locale, accept-language
}
Copied!
Default
| enabled = 0 languageHeader = x-locale, accept-language

autoMerge

Property
autoMerge
Data type
array
Description

Controls if the JSON-data should automatically be merged with the Model. By default, autoMerge is enabled. This can be changed by setting enabled = 0.

It is also possible to enable / disable autoMerge for every endpoint individually by using the @Api\AutoMerge() annotation.

Read more here.

plugin.tx_nnrestapi.settings.autoMerge {
    
    // disable autoMerge globally (default is 1 / enabled)
    enabled = 0

}
Copied!
Default
enabled = 1

response.headers

Property
response.headers
Data type
array
Description

Allows you to add, modify or remove the default headers sent to the frontend.

You can define simple key/value pairs here that will be sent with every response. All headers are sent without parsing or modification, with one exception: The header for Access-Control-Allow-Origin:

As the Access-Control-Allow-Origin sent by PHP usually can not handle wildcards in parts of the URL (e.g. *.mysite.com), the list of URLs for this header are parsed by the nnrestapi.

If one of the given patterns matches the HTTP_ORIGIN or HTTP_REFERER, the header will be set to the exact domain that the request was sent from. This allows setting Access-Control-Allow-Credentials: true which can be useful in cross-domain requests.

Find out, which Default headers are sent and how to modify and add response headers.

plugin.tx_nnrestapi.settings.response.headers {
    
    // Restrict CORS to certain domains
    Access-Control-Allow-Origin = localhost:8090, *.mysite.com, https://www.otherdomain.de
}
Copied!

Here is an example list of patterns:

pattern Example ORIGIN / REFERER matched?
localhost
🟢 yes
🟢 yes 🟢 yes
localhost:* | http://localhost:8090 http://localhost | 🟢 yes 🟢 yes
localhost:8010
🟢 yes
🔴 no 🔴 no
*.mysite.com
🟢 yes
🟢 yes
🟢 yes 🔴 no
https://*.mysite.com
🔴 no
🟢 yes
🔴 no 🟢 yes
* any 🟢 yes
Default
| Access-Control-Allow-Origin = *

security.defaults

Property
security.defaults
Data type
array
Description

Adds global hooks to perform security checks before accessing an endpoint.

You can add your custom hooks here. Your hook should return TRUE or FALSE depending on the result of the check. If it returns FALSE the Api will respond with a 403 status code.

plugin.tx_nnrestapi {
   settings {
      security {
         defaults {
            10 = \Nng\Nnrestapi\Utilities\Security->checkInjections
            20 = \Nng\Nnrestapi\Utilities\Security->checkLocked
         }
      }
   }
}
Copied!
Default
| enabled = 0 languageHeader = x-locale, accept-language

timeZone

Property
timeZone
Data type
string
Description

Override the time zone settings from TYPO3 or the server when processing the request.

Try UTC or Europe/Berlin here, if you are experiencing a one-hour offset when using JavaScript datepicker components in the frontend.

If empty will use the time zone settings from the server or as defined in the LocalConfiguration under [SYS][phpTimeZone].

You can find a list of time zones on this website.

plugin.tx_nnrestapi.settings.timeZone = UTC
Copied!
Default
empty