### Example GET requests for standard routing

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Requests/Requests/30_Variables.html

Example GET requests that are routed to the Example->getNewsAction() method when using standard routing.

```text
https://www.mysite.com/api/example/news/
https://www.mysite.com/api/example/news/1
https://www.mysite.com/api/example/news/article
https://www.mysite.com/api/example/news/article/1
https://www.mysite.com/api/example/news/article/1/2/3

```

--------------------------------

### VanillaJS starter template HTML

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Examples/Examples/LegacyJS/10_simple.rst.txt

A complete HTML starter template for a VanillaJS demo that connects to the nnrestapi. Includes Bootstrap CSS from a CDN. Copy and paste to get started.

```html
<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>nnrestapi VanillaJS Demo</title>

        <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">
```

--------------------------------

### Full UploadPathHelper class example

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Annotations/Annotations/60_Upload.rst.txt

Full example of a custom upload path helper that returns a date-based folder path.

```php
<?php

namespace My\Extension\Helper;

class UploadPathHelper
{
   /**
    * Return upload-path based on current date (e.g. `1:/api/2021-12/`)
    * 
    * @return array
    */
   public static function getPathForDate( $request = null, $settings = null ) 
   {
      return [
         'defaultStoragePath' => '1:/api/' . date('Y-m') . '/'
      ];
   }

}
```

--------------------------------

### Get request settings with $this->request->getSettings()

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Requests/Requests/30_Variables.html

Returns the settings for the current request, including the instructions for processing the data defined in the TypoScript setup.

```text
[
   ...
   'fileUploads' => [
       'default' => [
           'defaultStoragePath' => '1:/api/',
           'file' => '1:/api/tests/',
        ]
   ],
   'globalDistillers' => [
       'TYPO3\CMS\Extbase\Domain\Model\Category' => [
           'exclude' => 'parent'
        ]
   ]
   ...
]
```

--------------------------------

### GET request URL for the custom checkAccess() example

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Access/Access/Annotation.html

The URL to reach the example endpoint with a GET request. The endpoint is accessible only if the custom checkAccess() method returns TRUE.

```text
https://www.mysite.com/api/test/example

```

--------------------------------

### Set string example data with @Api\Example

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Annotations/Annotations/30_Example.rst.txt

Adds a simple string as example data for the request body in the backend module's test bed.

```php
@Api\Example("this is an example")
```

--------------------------------

### Set JSON example data with @Api\Example

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Annotations/Annotations/30_Example.rst.txt

Adds a JSON-formatted string as example data for composing a JSON request in the test bed.

```php
@Api\Example("{'username':'david', 'password':'mypassword'}")
```

--------------------------------

### Example URLs for default routing

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Requests/Requests/10_Standard.html

Two example URLs showing the default routing pattern: one with a string method name and one with an integer method name.

```text
https://www.mywebsite.com/api/article/all
https://www.mywebsite.com/api/article/1
```

--------------------------------

### HTTP Basic Auth request examples for TYPO3 REST API (PHP, axios, jQuery, pure JS)

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Authentication/Authentication/10_http_auth.rst.txt

These examples show how to send HTTP Basic Auth requests to the TYPO3 REST API using PHP, axios, jQuery, and pure JavaScript. Each snippet sets the Authorization header with base64-encoded credentials and handles the response. The PHP example uses file_get_contents with credentials in the URL; the axios example uses the auth option; the jQuery example sets the header manually; the pure JS example uses fetch with a manually constructed Authorization header.

```php
<?php

$username = 'john';
$apiKey = 'xxxx';
$uri = 'www.yourserver.com/api/your/endpoint';

$result = file_get_contents("https://{$username}:{$apiKey}@{$uri}');
$arr = json_decode($result, true);

print_r( $arr );
```

```javascript
const requestUrl = 'https://www.yourserver.com/api/your/endpoint';
const method = 'get';
const json = {title:'Test'};

const auth = {
   username: 'john',
   password: 'xxxx'
};

axios({
      method: method,
      url: requestUrl,
      data: json,
      auth: auth
}).then( ({data}) => {
      console.log( data );
}).catch( ({response}) => {
      console.log( response.data );
});
```

```javascript
var method = 'GET';
var url = 'https://www.mywebsite.com/api/endpoint';

var username = 'john';
var password = 'xxxx';

var payload = JSON.stringify({
   title: 'Test'
});

$.ajax({
   url: url,
   type: method,
   data: payload,
   crossDomain: true,
   beforeSend: function (xhr) {
      xhr.setRequestHeader('Authorization', 'Basic ' + btoa(username + ':' + password));
   },
}).done(function (result) {
   $('#result').text( JSON.stringify(result) );
}).fail(function (error) {
   alert( 'Error ' + error.status + ': ' + error.responseJSON.error );
   $('#result').text( 'ERROR: ' + JSON.stringify(error) );
});
```

```javascript
const url = 'https://www.mywebsite.com/api/your/endpoint';

const auth = {
   username: 'john',
   password: 'xxxx'
};

const xhrConfig = {
   method: 'GET',
   headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Basic ' + btoa(`${auth.username}:${auth.password}`)
   },
};

fetch( url, xhrConfig )
   .then( async response => {

      // convert the result to a JavaScript-object
      let data = await response.json()

      if ( !response.ok ) {
            // reponse was not 200
            alert( `Error ${response.status}: ${data.error}` );
      } else {
            // everything ok!
            console.log( data );
      }
   });
```

--------------------------------

### Example URL for GET request with uid

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Examples/Examples/10_creating_an_api.rst.txt

Shows the URL format for accessing the Article endpoint with a uid. The uid is passed as the last part of the URL and is automatically mapped to the $uid argument.

```php
https://www.mysite.com/api/article/1
```

--------------------------------

### Frontend API request examples in PHP, JavaScript (fetch, XHR, Axios, jQuery)

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Localization/Index.html

These examples show how to call a REST API endpoint with different HTTP clients: PHP cURL, JavaScript fetch, XMLHttpRequest, Axios, and jQuery. Each sets the Accept-Language header to request localized content. The PHP example includes an optional SSL verification disable for certificate issues; the fetch example handles non-OK responses by alerting the error; the XHR example alerts on HTTP errors and network errors; Axios and jQuery handle errors via their promise/callback mechanisms.

```php
<?php

$url = 'https://www.mysite.com/api/endpoint';
$language = 'en-EN';

$headers = [
   'Accept: application/json',
   'Accept-Language: ' . $language
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

// only include if you are having problems with SSL certificate
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);

$json = curl_exec($curl);
curl_close($curl);

$data = json_decode( $json, true );

$dump = htmlspecialchars( print_r( $data, true ) );
echo "<pre>{$dump}";


```

```javascript
const url = 'https://www.mysite.com/api/endpoint';
const language = 'de-DE';

const xhrConfig = {
   method: 'GET',
   headers: {
      'Content-Type': 'application/json',
      'Accept-Language': language
   },
};

fetch( url, xhrConfig )
      .then( async response => {

      let data = await response.json()

      if ( !response.ok ) {
         alert( `Error ${response.status}: ${data.error}` );
      } else {
         console.log( data );
         document.getElementById('result').innerText = data.html;
      }
   });


```

```javascript
var url = 'https://www.mysite.com/api/endpoint';
var language = 'en-EN';

var xhr = new XMLHttpRequest();
xhr.overrideMimeType('application/json');

xhr.open('get', url);
xhr.setRequestHeader('Accept-Language', language);

xhr.onload = function () {
   var data = JSON.parse( xhr.responseText );
   if (xhr.status != 200) {
      alert('Error!');
   }
   console.log( data );
};

xhr.onerror = function () {
   alert('Some other error... probably wrong url?');
};

xhr.send();


```

```javascript
const url = 'https://www.mysite.com/api/endpoint';
const language = 'en-EN';

const headers = {
   'Accept-Language': language
};

axios({
   method: 'get',
   url: url,
   headers: headers
}).then( ({data}) => {
   console.log( data );
}).catch( ({response}) => {
   console.log( response.data );
});


```

```javascript
const url = 'https://www.mysite.com/api/endpoint';
const language = 'en-EN';

const headers = {
   'Accept-Language': language
};

$.ajax({
   url: url,
   type: 'GET',
   headers: headers
}).done((data) => {
   console.log( data );
}).fail((error) => {
   alert( `Error ${error.status}: ${error.responseJSON.error}` );
});


```

--------------------------------

### Example URLs routed to getNewsAction

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Requests/Requests/30_Variables.rst.txt

Example URLs that are routed to the Example->getNewsAction() method when using standard routing. The method name determines the endpoint.

```php
https://www.mysite.com/api/example/news/
https://www.mysite.com/api/example/news/1
https://www.mysite.com/api/example/news/article
https://www.mysite.com/api/example/news/article/1
https://www.mysite.com/api/example/news/article/1/2/3
```

--------------------------------

### Accept-Language header examples

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Localization/Localization/10_backgrounds.html

Shows three example Accept-Language headers for German, French, and Italian, each sent with the same URI to request localized content.

```http
// Ick sprecke Deutsch!
Accept-Language: de-DE

// Je parle Baguette
Accept-Language: fr-FR

// Il pablo Parmegano
Accept-Language: it-IT

```

--------------------------------

### Accept-Language header examples

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Localization/Localization/10_backgrounds.rst.txt

Shows example Accept-Language headers for German, French, and Italian. These headers are sent with the request to indicate the desired language.

```php
// Ick sprecke Deutsch!
Accept-Language: de-DE

// Je parle Baguette
Accept-Language: fr-FR

// Il pablo Parmegano
Accept-Language: it-IT
```

--------------------------------

### Full example of an API endpoint with @Api\Example

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Annotations/Annotations/30_Example.html

Complete class example showing the @Api\Example annotation used in an endpoint method. The class extends AbstractApi and uses the @Api\Endpoint and @Api\Access annotations.

```php
<?php

namespace My\Extension\Api;

use Nng\Nnrestapi\Annotations as Api;
use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Example("this is an example")
    * @Api\Access("public")
    *
    * @return array
    */
   public function getAllAction()
   {
      return ['nice'=>'result'];
   }

}

```

--------------------------------

### Example response JSON from nnrestapi file upload

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Examples/Examples/Axios/30_fileuploads.html

Example response from the nnrestapi after processing the multipart upload. The 'UPLOAD:/myfile' placeholder is replaced with the file path 'fileadmin/api/image.jpg'.

```json
{
    "title": "This is the title",
    "text": "This is the bodytext",
    "image": "fileadmin/api/image.jpg"
}

```

--------------------------------

### Full example of @Api\Access usage

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Access/Index.html

Full example of a TYPO3 REST API endpoint class using the @Api\Access annotation. Requires the use statement 'use Nng\Nnrestapi\Annotations as Api;' at the top of the script.

```php
<?php
namespace My\Extension\Api;

use Nng\Nnrestapi\Annotations as Api;
use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */
class Test extends AbstractApi
{
   /**
    * @Api\Access("public")
    * @return array
    */
   public function getExampleAction()
   {
      return ['result'=>'welcome!'];
   }
}
```

--------------------------------

### Define multiple access groups in site YAML or TypoScript Setup

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Access/Index.html

Defines multiple access groups with different user types and combinations. The identifier names are arbitrary; you can choose any names that make sense for your setup.

```yaml
nnrestapi:
   accessGroups:
      limitedUser: fe_users[david,marc]
      adminUsers: fe_users[1,2,3], be_users, be_admins
      viewOnlyUsers: fe_groups[apiViewers]

```

```typoscript
plugin.tx_nnrestapi.settings {
   accessGroups {
      limitedUser = fe_users[david,marc]
      adminUsers = fe_users[1,2,3], be_users, be_admins
      viewOnlyUsers = fe_groups[apiViewers]
   }
}

```

--------------------------------

### basic.apiKeys configuration example

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Configuration/Configuration/30_extmanager.html

Configure global API users in the Extension Manager. Each line contains a username and API key separated by a colon. The default user 'examplefeUserName' is excluded from access.

```text
user1:theApiKeyOfUser1 user2:theApiKeyOfUser2
```

--------------------------------

### Get list of all countries using nnhelpers

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Responses/Responses/10_Simple.html

Example using EXT:nnhelpers to fetch all static countries from the database and return them as an array.

```php
/**
 * Get list of all static countries from the database
 *
 * @Api\Access("public")
 * @return array
 */
public function getCountriesAction()
{
   $countries = \nn\t3::Environment()->getCountries();
   return $countries;
}

```

--------------------------------

### @Api\Access() annotation examples

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Authentication/Authentication/10_http_auth.html

Examples of @Api\Access() annotations to control endpoint access. Use "api_users" for all API users, "api_users[john]" for a specific user, or "config[myUsers]" for users defined in TypoScript setup.

```php
// Expose this endpoint to ALL api_users
@Api\Access("api_users")

// ... or only to the user "john"
@Api\Access("api_users[john]")

// ... or to the users defined in the TypoScript setup
@Api\Access("config[myUsers]")

```

--------------------------------

### basic.apiKeys example format

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Configuration/Configuration/30_extmanager.rst.txt

Shows the expected format for the basic.apiKeys setting: one user per line, with username and API key separated by a colon. The default value is 'examplefeUserName:exampleApiKey'.

```text
user1:theApiKeyOfUser1
user2:theApiKeyOfUser2
```

--------------------------------

### Change default header value in TypoScript

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Responses/Responses/30_Headers.rst.txt

Set a new value for an existing header key in the TypoScript setup. This example changes Access-Control-Allow-Credentials to false.

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

--------------------------------

### Configure global HTTP Basic Auth API keys (basic.apiKeys)

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Authentication/Authentication/10_http_auth.rst.txt

Enter global HTTP Basic Auth credentials in the extension configuration field "API-Keys for BasicAuth" (basic.apiKeys). Each line contains a username and password separated by a colon.

```bash
username_1:password_1
username_2:password_2
username_3:password_3
...
```

--------------------------------

### @Api\Access() annotation examples for HTTP Basic Auth

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Authentication/Authentication/10_http_auth.html

Examples of @Api\Access() annotations to expose endpoints to all fe_users with an apiKey, to a specific fe_user 'john', or to users defined in TypoScript setup. These annotations are used to set the correct rights for endpoints accessible via HTTP Basic Auth.

```php
// Expose this endpoint to ALL fe_users that have an apiKey
@Api\Access("api_users")

// ... or only to the fe_user "john"
@Api\Access("api_users[john]")

// ... or to the users defined in the TypoScript setup
@Api\Access("config[myUsers]")

```

--------------------------------

### VanillaJS starter template for nnrestapi demo

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Examples/Examples/PlainJS/10_simple.html

Full copy-and-paste starter template for a VanillaJS demo of the nnrestapi. It builds a Bootstrap form that lets you pick a request method (GET, POST, PUT, PATCH), enter an endpoint URL, a title, and a body text, then sends the request with fetch and displays the JSON response in a <pre> element. The script sets the Content-Type header to application/json and only includes a JSON body for methods other than GET and DELETE; on a non-OK response it alerts with the status and the error field from the response JSON.

```html
<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>nnrestapi VanillaJS Demo</title>

        <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">

        <style>
            #json-data {
                min-height: 100px;
            }
            #result {
                min-height: 100px;
                white-space: pre-wrap;
                border: 1px dashed #aaa;
                background: #eee;
                padding: 0.75rem;
            }
        </style>
    </head>
    <body>
        <div class="container my-5">
            <div class="form-floating mb-4">
                <select class="form-select" id="request-method">
                <option>GET</option>
                <option>POST</option>
                <option>PUT</option>
                <option>PATCH</option>
                </select>
                <label for="request-method">Request method</label>
            </div>
            <div class="form-floating mb-4">
                <input class="form-control" id="url" value="https://www.mysite.com/api/index/" />
                <label for="url">URL to endpoint</label>
            </div>
            <div class="form-floating mb-4">
                <input class="form-control" id="title" value="This is the title" />
                <label for="json-data">Title</label>
            </div>
            <div class="form-floating mb-4">
                <textarea class="form-control" id="text">This is the bodytext</textarea>
                <label for="json-data">Text</label>
            </div>
            <div class="form-floating mb-4">
                <button id="submit" class="btn btn-primary">Send to API</button>
            </div>
            <pre id="result">Result</pre>
        </div>

        <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7XsPsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>
        <script>

            const $method = document.getElementById('request-method');
            const $url = document.getElementById('url');
            const $title = document.getElementById('title');
            const $text = document.getElementById('text');
            const $button = document.getElementById('submit');
            const $result = document.getElementById('result');

            $button.addEventListener('click', submitData);

            function submitData() {

                const url = $url.value;
                const method = $method.value;

                const json = {
                    title: $title.value,
                    text: $text.value
                };

                const xhrConfig = {
                    method: method,
                    headers: {
                        'Content-Type': 'application/json',
                    }
                };

                if (['GET', 'DELETE'].indexOf(method) == -1) {
                     xhrConfig.body = JSON.stringify(json);
                }

                fetch( url, xhrConfig )
                    .then( async response => {
                        let data = await response.json()
                        if ( !response.ok ) {
                            alert( `Error ${response.status}: ${data.error}` );
                        } else {
                            $result.innerText = JSON.stringify( data );
                        }
                    });
            }

        </script>
    </body>
</html>

```

--------------------------------

### GET request URL for article uid

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Examples/Examples/10_creating_an_api.html

Example URL for retrieving an article by uid. The integer at the end is automatically mapped to the $uid argument and triggers the getIndexAction().

```text
https://www.mysite.com/api/article/1

```

--------------------------------

### Full axios starter template with login form and testbed for TYPO3 REST API

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Examples/Examples/Axios/20_auth.html

Full starter template for an axios-based login form and testbed against a TYPO3 REST API. Includes a login form that authenticates a frontend user and stores the returned token as a default Authorization header, then shows a test form for sending GET, POST, PUT, PATCH, and DELETE requests. Requires the axios library and a valid auth endpoint URL; errors are shown via alert with the response status and error message.

```html
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>nnrestapi axios Demo with authentication</title>

    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">

    <style>
        #json-data {
            min-height: 100px;
        }
        #result {
            min-height: 100px;
            white-space: pre-wrap;
            border: 1px dashed #aaa;
            background: #eee;
            padding: 0.75rem;
        }
    </style>
</head>
<body>

    <div class="container my-5" id="login-form">
        <div class="form-floating mb-4">
            <input class="form-control" id="url-auth" value="https://www.mysite.com/api/auth" />
            <label for="url-auth">URL to auth-endpoint</label>
        </div>
        <div class="form-floating mb-4">
            <input class="form-control" id="username" value="" />
            <label for="username">Username</label>
        </div>
        <div class="form-floating mb-4">
            <input type="password" class="form-control" id="password" value="" />
            <label for="password">password</label>
        </div>
        <div class="form-floating mb-4">
            <button id="btn-login" class="btn btn-primary">Login</button>
        </div>
    </div>

    <div class="container my-5 d-none" id="test-form">
        <div class="form-floating mb-4">
            <select class="form-select" id="request-method">
                <option>GET</option>
                <option>POST</option>
                <option>PUT</option>
                <option>PATCH</option>
                <option>DELETE</option>
            </select>
            <label for="request-method">Request method</label>
        </div>
        <div class="form-floating mb-4">
            <input class="form-control" id="url-request" value="https://www.mysite.com/api/user" />
            <label for="url">URL to endpoint</label>
        </div>
        <div class="form-floating mb-4">
            <textarea class="form-control" id="json-data">{"title":"Test"}</textarea>
            <label for="json-data">JSON data</label>
        </div>
        <div class="form-floating mb-4">
            <button id="btn-request" class="btn btn-primary">Send to API</button>
        </div>
        <pre id="result"></pre>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js"></script>
    <script>

        /**
         * Login form
         *
         */
        document.getElementById('btn-login').addEventListener('click', () => {

            const authUrl = document.getElementById('url-auth').value;

            const credentials = {
                username: document.getElementById('username').value,
                password: document.getElementById('password').value
            };

            // Authenticate frontend user
            axios.post(authUrl, credentials).then(({data}) => {

                // set default headers for all future requests
                axios.defaults.withCredentials = true;
                axios.defaults.headers.common.Authorization = `Bearer ${data.token}`;

                document.getElementById('login-form').classList.add('d-none');
                document.getElementById('test-form').classList.remove('d-none');

            }).catch(({response}) => {
                alert( `Error ${response.status}: ${response.data.error}` );
            });

        });

        /**
         * Test form
         *
         */
        document.getElementById('btn-request').addEventListener('click', () => {

            const requestUrl = document.getElementById('url-request').value;

            axios({
                url: requestUrl,
                method: document.getElementById('request-method').value,
                data: document.getElementById('json-data').value
            }).then(({data}) => {
                document.getElementById('result').innerText = JSON.stringify( data );
            }).catch(({response}) => {
                alert( `Error ${response.status}: ${response.data.error}` );
            });

        });

    </script>
</body>
</html>

```

--------------------------------

### Send GET request with Accept-Language header using axios and jQuery

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Localization/Index.rst.txt

Two JavaScript examples showing how to send a GET request with an 'Accept-Language' header to a REST API endpoint. The first uses axios, the second uses jQuery's $.ajax. Both set the language to 'en-EN' and handle success and error responses.

```javascript
const url = 'https://www.mysite.com/api/endpoint';
const language = 'en-EN';

const headers = {
   'Accept-Language': language
};

axios({
   method: 'get',
   url: url,
   headers: headers
}).then( ({data}) => {
   console.log( data );
}).catch( ({response}) => {
   console.log( response.data );
});
```

```javascript
const url = 'https://www.mysite.com/api/endpoint';
const language = 'en-EN';

const headers = {
   'Accept-Language': language
};
      
$.ajax({
   url: url,
   type: 'GET',
   headers: headers
}).done((data) => {
   console.log( data );
}).fail((error) => {
   alert( `Error ${error.status}: ${error.responseJSON.error}` );
});
```

--------------------------------

### VanillaJS starter template with login form

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Examples/Examples/LegacyJS/20_auth.html

Starter template with a login form and a test form for sending JSON requests (GET, POST, PUT, PATCH, DELETE) to a TYPO3 REST API. It includes Bootstrap 5 styling and a helper function for older browsers that do not support `fetch()`. The code is truncated at the end of the provided source.

```html
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>nnrestapi axios Demo with pure JavaScript for older browser</title>

    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">

    <style>
        #json-data {
            min-height: 100px;
        }
        #result {
            min-height: 100px;
            white-space: pre-wrap;
            border: 1px dashed #aaa;
            background: #eee;
            padding: 0.75rem;
        }
    </style>
</head>
<body>

    <div class="container my-5" id="login-form">
        <div class="form-floating mb-4">
            <input class="form-control" id="url-auth" value="https://www.mysite.com/api/auth" />
            <label for="url-auth">URL to auth-endpoint</label>
        </div>
        <div class="form-floating mb-4">
            <input class="form-control" id="username" value="" />
            <label for="username">Username</label>
        </div>
        <div class="form-floating mb-4">
            <input type="password" class="form-control" id="password" value="" />
            <label for="password">password</label>
        </div>
        <div class="form-floating mb-4">
            <button id="btn-login" class="btn btn-primary">Login</button>
        </div>
    </div>

    <div class="container my-5 d-none" id="test-form">
        <div class="form-floating mb-4">
            <select class="form-select" id="request-method">
                <option>GET</option>
                <option>POST</option>
                <option>PUT</option>
                <option>PATCH</option>
                <option>DELETE</option>
            </select>
            <label for="request-method">Request method</label>
        </div>
        <div class="form-floating mb-4">
            <input class="form-control" id="url-request" value="https://www.mysite.com/api/endpoint/somewhere" />
            <label for="url">URL to endpoint</label>
        </div>
        <div class="form-floating mb-4">
            <textarea class="form-control" id="json-data">{"title":"Test"}</textarea>
            <label for="json-data">JSON data</label>
        </div>
        <div class="form-floating mb-4">
            <button id="btn-request" class="btn btn-primary">Send to API</button>
        </div>
        <pre id="result"></pre>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>
    <script>

        /**
         * Helper-function to send REST Api requests for older
         * browsers not supporting fetch()
         *
         */
        function sendRequest( url, payload, method, done, fail ) {

```

--------------------------------

### Set @Api\Access() annotations for JWT-protected endpoints

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Authentication/Authentication/20_jwt.html

Shows how to restrict endpoint access using the @Api\Access() annotation. The examples expose the endpoint to all fe_users, a specific user by username, users by uid, or users defined in TypoScript setup.

```php
// Expose this endpoint to ALL fe_users that have an apiKey
@Api\Access("fe_users")

// ... or only to the fe_user "john"
@Api\Access("fe_users[john]")

// ... or only to the fe_users with uid 2 or 3
@Api\Access("fe_users[2,3]")

// ... or to the users defined in the TypoScript setup
@Api\Access("config[myUsers]")
```

--------------------------------

### Example result of the upload

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Examples/Examples/jQuery/30_fileuploads.html

JSON response showing the uploaded data with the placeholder replaced by the file path.

```json
{
    "title": "This is the title",
    "text": "This is the bodytext",
    "image": "fileadmin/api/filename.jpg"
}

```

--------------------------------

### PHP cURL request with Accept-Language header

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Localization/Index.rst.txt

PHP example using cURL to send a GET request with an Accept-Language header to retrieve localized data. The response is JSON-decoded and printed with htmlspecialchars. The SSL verification is disabled only if you have SSL problems.

```php
<?php

$url = 'https://www.mysite.com/api/endpoint';
$language = 'en-EN';

$headers = [
   'Accept: application/json',
   'Accept-Language: ' . $language
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

// only include if you are having problems with SSL
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);

$json = curl_exec($curl);
curl_close($curl);

$data = json_decode( $json, true );

$dump = htmlspecialchars( print_r( $data, true ) );
echo "<pre>{$dump}";
```

--------------------------------

### Get raw content data with getRawAction

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Examples/Examples/13_raw.rst.txt

Creates a public endpoint that returns raw tt_content data for a given uid, including FAL relations. The request URL and an example JSON response are shown. The bodytext contains an unrendered t3://page typolink.

```php
<?php   
namespace My\Extension\Api;

use Nng\Nnrestapi\Annotations as Api;
use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */
class Content extends AbstractApi 
{
  /**
   * @Api\Access("public")
   * @Api\Localize()
   * 
   * @param int $uid
   * @return array
   */
   public function getRawAction( int $uid = null )
   {
      // Get raw data from table tt_content and include FAL-relations
      $data = \nn\t3::Content()->get( $uid, true );
      return $data;
   }
}

```

```php
https://www.mysite.com/api/content/raw/{uid}

```

```json
{
   "uid": 1,
   "pid": 2,
   "header": "My title",
   "bodytext": "<p>This is <a href=\"t3://page?uid=6\">link to a page</a></p>",
   "assets": [
      "uid": 14,
      "publicUrl": "fileadmin/path/to/image.jpg"
   ],
   ...
}

```

--------------------------------

### Example API URLs for content from column

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Examples/Examples/12_pages.html

Example URLs to retrieve rendered content for a given page UID and column position. The first URL fetches content from page 123, column 0; the second from page 99, column 110.

```text
// GET all content-elements from page 123 and column 0
https://www.mysite.com/api/content/column/123/0

// GET all content-elements from page 99 and column 110
https://www.mysite.com/api/content/column/99/110

```

--------------------------------

### Full example: Article API endpoint with @Api\Access("public")

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Examples/Examples/10_creating_an_api.html

Full example of an API endpoint class exposing read and write actions with public access. The source explicitly warns not to use @Api\Access("public") in production; restrict access via 403 responses or annotations as described in the Restricting Access chapter. The class handles GET, PUT, POST, and DELETE actions for an Article model, returning notFound responses when the article is missing.

```php
<?php
namespace My\Extension\Api;

use Nng\Nnrestapi\Annotations as Api;
use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */
class Article extends AbstractApi
{
   /**
    * GET an article via: /api/article/{uid}
    *
    * @Api\Access("public")
    * @param My\Extension\Domain\Model\Article $article
    */
   public function getIndexAction( $article = null )
   {
      if (!$article) {
         return $this->response->notFound('Requested Article was not found.');
      }
      return $article;
   }

   /**
    * UPDATE an article via: /api/article/{uid}
    *
    * @Api\Access("public")
    * @param My\Extension\Domain\Model\Article $article
    */
   public function putIndexAction( $article = null )
   {
      if (!$article) {
         return $this->response->notFound('Requested Article was not found.');
      }
      \nn\t3::Db()->update( $article );
      return $article;
   }

   /**
    * INSERT a new article via: /api/article
    *
    * @Api\Access("public")
    * @param My\Extension\Domain\Model\Article $article
    */
   public function postIndexAction( $article = null )
   {
      $insertedArticle = \nn\t3::Db()->insert( $article );
      return $insertedArticle;
   }

   /**
    * DELETE an article via: /api/article/{uid}
    *
    * @Api\Access("public")
    * @param My\Extension\Domain\Model\Article $article
    */
   public function deleteIndexAction( $article = null )
   {
      if (!$article) {
         return $this->response->notFound('Requested Article was not found.');
      }
      \nn\t3::Db()->delete( $article );
      return $article;
   }
}

```

--------------------------------

### Use Markdown in @Api\Example documentation

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Annotations/Annotations/30_Example.html

Shows how to include Markdown in the annotation's docblock to create rich documentation in the backend module. The example includes a code block and the @Api\Example annotation for the testbed request.

```php
/**
 * ## Example
 *
 * This comment will be visible in the backend-module of
 * the nnrestapi. If you would like to show a code block in
 * your documentation, simple use the markdown-syntax:
 * ```
 * {"some":"example from markdown"}
 * ```
 * The text in the Example-annotation will be used to compose
 * the request from the testbed.
 *
 * @Api\Example("{'some':'example for testbed'}")
 * @return array
 */

```

--------------------------------

### Send a POST request with JSON payload using fetch()

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Examples/Examples/PlainJS/10_simple.html

Sends a POST request (or PUT, PATCH, DELETE) with a JSON payload to the TYPO3 Restful API. By default, the request is routed to Index->postIndexAction(). The request includes the 'Content-Type: application/json' header and the body is stringified JSON. The response is handled similarly to the GET example, with error alerting and console logging.

```javascript
// By default this will be routed to Index->postIndexAction()
const url = 'https://www.mywebsite.com/api/index';

const json = {
    title: 'Title',
    text: 'Text to send',
};

const xhrConfig = {
    method: 'POST', // or: 'PUT', 'PATCH', 'DELETE' ...
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(json)
};

fetch( url, xhrConfig )
    .then( async response => {
        let data = await response.json()
        if ( !response.ok ) {
            alert( `Error ${response.status}: ${data.error}` );
        } else {
            console.log( data );
        }
    });
```

--------------------------------

### HTML starter template with login form

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Examples/Examples/Axios/20_auth.rst.txt

HTML starter template for an axios demo with a login form. It includes Bootstrap 5 CSS, a login form with fields for the auth URL, username, and password, and a login button. The template is intended to be used with JavaScript to handle authentication and send JSON requests.

```html
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>nnrestapi axios Demo with authentication</title>

    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">

    <style>
        #json-data {
            min-height: 100px;
        }
        #result {
            min-height: 100px;
            white-space: pre-wrap;      
            border: 1px dashed #aaa;
            background: #eee;
            padding: 0.75rem;
        }
    </style>
</head>
<body>

    <div class="container my-5" id="login-form">
        <div class="form-floating mb-4">
            <input class="form-control" id="url-auth" value="https://www.mysite.com/api/auth" />
            <label for="url-auth">URL to auth-endpoint</label>
        </div>
        <div class="form-floating mb-4">
            <input class="form-control" id="username" value="" />
            <label for="username">Username</label>
        </div>
        <div class="form-floating mb-4">
            <input type="password" class="form-control" id="password" value="" />
            <label for="password">password</label>
        </div>
        <div class="form-floating mb-4">
            <button id="btn-login" class="btn btn-primary">Login</button>
        </div>		
    </div>

</body>
</html>
```

--------------------------------

### Multiple IPs with @Api\Access("ip[...]") - equivalent syntaxes

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Access/Index.html

Three equivalent syntaxes for listing multiple IPs in the @Api\Access("ip[...]") annotation. Choose the syntax you remember best.

```php
@Api\Access("ip[90.120.10.*, 90.120.11.*]")
@Api\Access("ip[90.120.10.*], ip[90.120.11.*]")
@Api\Access({"ip[90.120.10.*]", "ip[90.120.11.*]"})

```

--------------------------------

### URL for custom route GET /test/route

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Requests/Requests/20_Custom.html

The URL that triggers the customRoutingTest() method when a GET request is sent.

```text
https://www.mysite.com/api/test/route
```

--------------------------------

### TypoScript configuration for fileUploads

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Annotations/Annotations/60_Upload.rst.txt

TypoScript setup for the fileUploads configuration. The default key sets the storage path and optionally a custom path finder class.

```typoscript
plugin.tx_nnrestapi.settings.fileUploads {

   # Use this key in your endpoint annotation "@api\upload default"
   default {

      // if nothing else fits, use fileadmin/api/
      defaultStoragePath = 1:/api/

      // Optional: Use a custom class to return configuration
      //pathFinderClass = Nng\Nnrestapi\Helper\UploadPathHelper::getUserUidPath
```

--------------------------------

### JSON data example

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Introduction/Index.html

Example of a JSON object used for communication between a JavaScript frontend and a backend in a REST API context.

```json
{"title":"Nice title", "text":"And this is the text!"}
```

--------------------------------

### Example parsed bodytext JSON response

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Examples/Examples/13_raw.html

Example result after parsing bodytext links. The t3://page link is converted to a relative URL.

```json
{
   "bodytext": "<p>This is <a href=\"/thepage\">linked to a page</a></p>",
   ...
}

```

--------------------------------

### Create a JSON request example

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Annotations/Annotations/30_Example.html

Use this annotation to provide a JSON example for the request body. The JSON is written as a string with single quotes.

```php
@Api\Example("{'username':'david', 'password':'mypassword'}")

```

--------------------------------

### Add a custom Kickstarter template with plugin.tx_nnrestapi.settings.kickstarts

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/Configuration/Configuration/10_typoscript.html

Configures a custom Kickstarter template for the REST Api backend module. The path must point to a zip or folder inside an EXT-folder or fileadmin. The replace map substitutes placeholders in the template source code during download.

```TypoScript
plugin.tx_nnrestapi.settings.kickstarts {
    myexample {

        // title and description for the list view
        title = A frontend in React
        description = Example React frontend connection with the TYPO3 Rest Api

        // 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#]
        }
    }
}

```

--------------------------------

### Full example with @Api\Cache annotation

Source: https://docs.typo3.org/p/nng/nnrestapi/main/en-us/_sources/Annotations/Annotations/20_Cache.rst.txt

Example endpoint class using the @Api\Cache annotation on the getAllAction method. The method's result is cached automatically.

```php
<?php

namespace My\Extension\Api;

use Nng\Nnrestapi\Annotations as Api;
use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */   
class Example extends AbstractApi
{
   /**
    * @Api\Cache
    * @Api\Access("public")
    *
    * @return array
    */
   public function getAllAction() 
   {
      $result = $this->someComplicatedOperation();
      return $result;
   }

}
```