Headers and CORS¶

Warning

The default configuration of the nnrestapi is very “open”: It allows cross-domain requests (CORS) and cookies. This is great for developing from a localhost environment or testing your API with tools like Postman or CodePen.

In a production environment, you should change these settings and make them more secure. Never allow access to your Api from domains that you don’t know and trust! The same applies to accepting cross-domain cookies!

Settings HTTP headers of your TYPO3 RestApi response¶

When creating the response, the nnrestapi sends a list of headers to make things as “compatible” as possible during development. By default, it also enables cross-domain-requests (CORS) and the setting of cross-domain-cookies.

Changing a default header value¶

If you would like to change a default header value sent by the nnrestapi, simply set the new value in your TypoScript setup using the existing key:

plugin.tx_nnrestapi.settings.response {
   headers {
      Access-Control-Allow-Credentials = false
   }
}

Adding additional headers to your response¶

To add another HTTP header to your response, add it to the TypoScript setup:

plugin.tx_nnrestapi.settings.response {
   headers {
      X-My-Special-Header = Some value
   }
}

Removing a header to your response¶

If you would like to remove any of the default headers sent by the extension, simply set the value in the TypoScript setup to an empty string:

plugin.tx_nnrestapi.settings.response {
   headers {
      Access-Control-Allow-Origin =
   }
}

Overview of default headers sent:¶

HTTP header type	Default value and explanation
`Access-Control-Allow-Origin`	`` The endpoint may be accessed from any* domain. Makes life easier during development, because you can test from a localhost or CodePen environment. Under the hood, nnrestapi is actually responding with the exact `HTTP_ORIGIN` so `Access-Control-Allow-Credentials` can be set to `true` and Cookies can be shared across domains Please refer to the configuration section for more information. Security Risk: Please consider changing this value! Find out why you should change it
`Access-Control-Allow-Credentials`	`true` Normally, cookies are not sent when making requests from a foreign domain or localhost environment. By sending `true` here in combination with using the `withCredentials` option in the JavaScript frontend application, Cookies can be shared across domains. This is useful to allow authenticating the TYPO3 Frontend User using the standard `fe_typo_user`-cookie. You should consider changing this to `false` in a production environment, if the only application accessing the API is running under the same domain or you are not authenticating using cookies.
`Access-Control-Allow-Methods`	`GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS` Before the “real” request is sent to the server, the frontend might send a preflight request to make sure, the request method for the real request is allowed With this header, our endpoint is saying: All request methods are allowed, so go on and send the actual request.
`Allow`	`GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS` Similar to above, find out more
`Cache-Control`	`no-store, no-cache, must-revalidate, max-age=0, post-check=0, pre-check=0, false` We are telling the browser / app not to cache the results. This will increase the number of requests to your server. Consider changing this value - or at least using @ApiCache() wherever you can.
`Pragma`	`no-cache` Same intention here as described under `Cache-Control`

Settings HTTP headers from within your Endpoint¶

Inside of your endpoint you can add, modify or remove headers from the response.

Here are examples:

public getExampleAction()
{
   // add a single header to the response
   $this->response->addHeader( 'Some-Header', 'the-header-value' );

   // add multiple headers to the response
   $this->response->addHeader([
      'Some-Header' => 'value 1',
      'Another-Header' => 'value 2',
   ]);

   // remove a header by passing an empty string or null
   $this->response->addHeader( 'Some-Header', '' );

   return ['hello' => 'everybody'];
}

Settings HTTP Cache-Control (max-age) headers¶

The cache is disabled by sending the default Cache-Control and Paragma headers above.

Here is how you can set your custom max-age Header:

public getExampleAction()
{
   $this->response->setMaxAge( 100 );
   return ['message' => 'see you again in more than 100s'];
}

Note that you can also set the Cache-Control: max-age header by using an Annotation.

More information can be found in the chapter @ApiMaxAge().