Is the extension free? 

Yes, but ...!

License 

This extension documentation is published under the CC BY-NC-SA 4.0 (Creative Commons) license

Authors 

Version

Language

en

Authors

www.99grad.de, David Bascom

Email

info@99grad.de

Simple, scaleable, flexible 

The goal of this extension was to develop a REST Api framework for TYPO3 that was simple to integrate, but as scalable and configurable as possible. Using Annotations to accomplish this, seemed obvious and intuitive to us (and others).

It should offer simple, comprehensible solutions for the three big challenges during the implementation: user-authentication, file-upload (including automatic FAL conversion) and localization.

We wanted to offer the possibility to route requests to Controller-methods - offering a standardized scheme, but also allowing custom route configurations, that includes parsing of custom request parameter.

We wanted to offer a good documentation with as many examples as possible. So you (and we) can copy and paste - no matter if you are a front- or backend-developer. And no matter if this is the first time you are building an Api in TYPO3 - or if you're an expert.

We've invested a lot of time in creating functional and editable examples on CodePen and also integrated a miniature "Postman" in the backend-module so you can test your endpoints without having to leave the TYPO3 environment.

Quick Walkthrough 

Overview of the installation and backend features of the extension.

What does this extension do? 

This extension makes implementing your own Rest Api with TYPO3 as a backend simple.

It takes care of all of the "dirty work" like parsing the JSON requests, moving uploaded files to their destination, converting JSON-data to Models and Models, ObjectStorages, SysFileRefences etc. back to a JSON for the Reponse.

It supports all standard HTTP Request Methods like GET, POST - and even can handle PUT, DELETE and PATCH including file-uploads, which is usually a headache when working with PHP and TYPO3.

You can implement a new endpoint with 3 - 5 lines of code. You can limit access-rights and configure file-upload-paths, caching and result-parsing using Annotations. And you can easily extend your Api with your own custom Annotations, if you like.

The extension comes equipped with endpoints for authenticating Frontend-Users via JWT (JSON Web Token), HTTP basic auth and cookies.

The backend module offers a test bed similar to Postman to compose requests without having to use an additional tool. This saves you time and keeps development and testing centralized in your project!

Comments and annotations above the methods of your endpoints are automatically parsed and converted to a beautiful documentation in the backend module. Development and documentation stay centralized!

|

Read on 

⊛ Frontend features: 

• Supports all common request types (GET, POST, DELETE, PUT, PATCH)
• Shipped with an endpoint for full frontend-user authentication
• Multiple authentication methods: JSON Web Tokens (JWT), fe-user-Cookies and HTTP-Authorization (Basic Auth)
• Possibility to retrieve hidden records in the Frontend (like a backend user)
• Full support for creating, adding and removing FileReferences from the frontend application
• Supports multipart/form-data requests to send file-uploads in combination with JSON-payloads
• Supports CORS for accessing the endpoint from cross-origins and while developing in localhost environments
• Automatic conversion of JSON-data to Models and vice-versa

⊛ Developing features: 

• Many, many examples. And even many more.
• Highly customizable and configurable
• Automatic and custom routing to endpoints
• Fastest possible integration, set up your implementation in 5 minutes
• Optional Caching-layer with one line of code
• A "kick-starter" feature for creating your own extension with one click

⊛ Backend module: 

• Automatic listing of all registered endpoints
• Automatic documentation of your endpoints from comments and annotations
• Test bed to send requests with parameters and file-uploads from backend

Limitations and demarcations: 

• We have completely focussed on the JSON-format. We currently see no need to support XML or other formats. But let's discuss!
• We are not strictly following all principles of a RESTful Api. One of them says a "things should be stateless". To a certain extend this contradicts the login mechanisms of TYPO3 which relies on sessions that are stored on the server. We like the concept of TYPO3 Frontend Users and the idea of having sessions. Sessions that you can store data in. So we have implemented them as one of the ways to authenticate.
• We are mixing some things here, which are strictly separated from each other in other extensions. One of them is: URLs are not strictly mapped to a certain Model, Storage or Entity. This way, nnrestapi can be used very versatile - even if your only intention is to map a URL-route to a method like the extension YAML Routes does.

Sorry, we've sneaked something in. 

This extension depends on EXT:nnhelpers which takes care of most of the hardcore conversions: from JSON to Model, Array to FAL, FAL-Uploads and other strenuous things...

If you look at the examples or source codes and see a line of code starting with \nn\t3 then this is what we are talking about. nnhelpers is basically just a wrapper for many methods and functions that TYPO3 offers and that have been hard to find or have changed from version to version. Using nnhelpers in our extensions has made it possible for our company to develop and update extensions faster.

Sorry for "sneaking this in" when you install nnrestapi... but it saved us many, many hours of lifetime.

Contribution workflow 

Please always first create an issue at Bitbucket before starting a change.

git clone https://bitbucket.org/99grad-team/nnrestapi/src/master/

This is why... 

We hope you will donate € 1,– (yes, just ONE fckn Euro!) for every project you have based on this extension. We won't be checking this. And we will not be pushing that.

| It's just one click. And it's up to you. But image, what difference it could make, if you just said "thank you" this way, because...

That's ONE EURO ... 

Damn. That was a lot of begging. We should really start learning hypnosis instead.

A simplified explanation 

If you are new to the topic or you are wondering, what a REST Api ("Representational State Transfer") is all about and why it is hyped, let's put it in a few simple words. This is no explanation, that a "real" programmer would accept. But therefore it will be easy to understand ;)

And yes, ok, we admit, we're writing this to get Google more interested in this text ;)

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

let data = JSON.parse('{"title":"Nice title", "text":"And this is the text!"}');
console.log( data.title );

data.title = 'A new title';
fetch('https://www.mysite.com/path/to/my/api', {
    method: 'POST',
    body: JSON.stringify(data)
});

https://www.mywebsite.com/api/shelf/1

https://www.mywebsite.com/api/shelf/1

// get the data
GET https://www.mywebsite.com/api/shelf/1

// write the data
POST https://www.mywebsite.com/api/shelf/1

High speed walk-through: Installation 

| For people, who know their way around TYPO3 – no words needed, only enough coffee :) You can find the scripts for the YAML-configuration and .htaccess below.

Step-by-step instruction 

1. Install the extension

   | Press the Retrieve/Update button and search for the extension key nnrestapi. Then import the extension from the repository.

   OR

   Search for the current version in the TYPO3 Extension Repository (TER). Download the t3x or zip version. Upload the file afterwards in the Extension Manager and activate it.

   OR

   Install the extension using composer on the command-line:

   composer require nng/nnrestapi

   Copied!

2. Make sure the database-tables were created

   In the TYPO3 backend, switch to the "Maintenance" module and click on "Analyze Database Structure". Create the database-tables for nnrestapi, if necessary. For more information, read here.

3. Include the TypoScript Templates on your Root-page

   Make sure, the static TypoScript configuration for "RestApi Configuration (nnrestapi)" was included on your root-page. To do so, follow the standard instructions on how to include TypoScript from extensions.

4. Include the YAML-Configuration

   Search for your site-configuration YAML, which is usually located either under typo3conf/sites/{name}/config.yaml or under config/sites/{name}/config.yaml.

   Include these two lines at the end of the configuration.

   imports:
     - { resource: "EXT:nnrestapi/Configuration/Yaml/default.yaml" }

   Copied!

   They take care of the basic Routing to the Api – another words: That all requests sent to /api/... find their way to your classes and methods.

5. Modify the .htaccess

   This step might not be necessary - it depends a lot on your hosting environment and PHP-settings. In most of our installations these two lines were necessary – otherwise we had problems with the frontend user-session / authorization.

   Insert these two lines after RewriteEngine On:

   RewriteCond %{HTTP:Authorization} ^(.*)
   RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]

   Copied!

6. Get started!

   Go to the RestApi backend module and have a look!

   Then head on to the Quickstart section to write your first own endpoint in less than 5 minutes!

Backend module with testbed 

While creating your own RestApi you don't need to use external tools like Postman. All registered endpoints automatically get listed in the backend module. By clicking on the compose-icon you can create your custom request in the backend including Frontend-User authentication and file-uploading.

Search and filter endpoints 

Search for registered endpoints in the backend and hide the default endpoints that come with the nnrestapi-extension.

Automatic documentation 

Use Markdown in your method annotations to automatically create the documentation. This saves a lot of time and keeps code and documentation at one place.

FrontendUser Authentication 

The nnrestapi extensions ships with a Authentication-layer for logging in frontend-users and setting Json Web Tokens (JWT). This allows development from localhost-environments which connect to a external development-server without CORS-problems.

You can test the login / logout from the testbed in the backend module:

FrontendUser Configuration 

Set an API-key for frontend users to authenticate using HTTP basic auth. Alternatively you can use JSON Web Tokens (JWT) or cookies.

Setting the checkbox "admin mode" will allow the frontend user to retrieve hidden records with relations. This would usually only be able for backend users.

Extension Configuration 

Define API-keys for global users (no frontend-user necessary) that can authenticate using HTTP basic auth. Set a session lifetime for your users - or create API-sessions that never expire.

Logging 

Requests and errors can be logged in the backend and simply be replayed for debugging errors.

The log module offers many options for filtering, sorting and viewing the log entries.

Logging Configuration 

Configure logging of API requests and errors in the Extension Manager. Enable request logging for debugging, set up error logging for production monitoring, and control privacy settings like IP anonymization.

CodePens to go wild on 

We've tried to give you as many practical examples for the frontend and backend as possible. Most of the examples are also on CodePen for you to copy, test and modify.

Walkthrough 

Overview of the installation and backend features of the extension.

Up and running in 5 minutes 

1. Install the nnrestapi extension

   Follow the instructions under Installation to install the nnrestapi extension.

2. Create an own extension

   To implement your own endpoints, you will need to create a new extension - or use one of your existing extensions.

   Define the dependencies to the nnrestapi extension in your extension. This is important, so TYPO3 loads your extension after the nnrestapi extension.

   This goes in the ext_emconf.php of your extension:

   $EM_CONF[$_EXTKEY] = [
      ...
      'constraints' => [
         'depends' => [
            'nnrestapi' => '1.1.0-0.0.0',
         ],
      ],
   ];

   Copied!

   In case your installation is running in composer-mode, this must be added to the composer.json of your extension.

   {
      ...
      "require": {
         "nng/nnrestapi": "^1.1"
      },
   }

   Copied!

3. Create your first endpoint

   Create a file located at Classes/Api/Demo.php in your extension with this code.

   Important: Note that the comments with @Api\Endpoint() and @Api\Access() are not just comments! They actually register your class as an Endpoint and define, who is allowed to access your method.

   <?php   
   namespace My\Extension\Api;
   
   use Nng\Nnrestapi\Annotations as Api;
   
   /**
    * @Api\Endpoint()
    */
   class Demo extends \Nng\Nnrestapi\Api\AbstractApi {
   
      /**
       * @Api\Access("public")
       * @return array
       */
      public function getExampleAction()
      {
         return ['great'=>'it works!'];
      }
   }

   Copied!

4. Clear the cache!

   Click on the "clear cache" icon in the backend. This will make sure, that nnrestapi rebuilds the cache file and includes your classes and endpoints.

   We had a focus on performance and caching, so get used to having to do this whenever you add new endpoints or make changes to the @Api-annotations of a method.

5. Call your endpoint

   Enter the URL https://www.yourdomain.com/api/demo/example to see the result!

The request type makes the difference! 

A typical project setup will have of a frontend application that requests something and a backend that retrieves this data from the database and returns it to the frontend application.

Many Single Page Applications (SPA) and Progressive Web Apps (PWA) nowadays are programmed in JavaScript and use the JSON format to communicate between the frontend and backend. Typically, the frontend app will want to do a number of things:

• Get data for an existing entry from the backend
• Create or insert a new entry, e.g. add a new item to the to-do or shopping list
• Update an existing entry
• and finally delete an item from the database

The idea behind a RESTful Api is to define endpoints (URLs) that the frontend application can communicate with to get the job done. But instead of defining separate URLs for every operation needed (/api/get/entry, /api/save/entry, /api/delete/entry) or passing an action as request parameter (?action=save) it uses HTTP Request types to make clear, if an entry should be retrieved, inserted, updated or deleted.

Same URL - different actions! 

Most of the time you even have the same URL for every operation - but depending on the type of request and the request-body passed, different operations are executed:

Route a request to endpoints 

The whole deal is about getting a certain HTTP Request Type "connected" to a Controller and method of your Api that will then take care of the rest: Retrieving, updating, inserting or deleting data.

There are two basic ways to accomplish this task:

• Routing by method-name
• Routing by custom Routes

Preparing a class to be used as an TYPO3 RestAPI Endpoint 

To make sure that the TYPO3 RestApi "knows" it can route a request to your class and method, you need to register the class.

There are two alternative ways this can be done:

• On a per-class base using the @Api\Endpoint() Annotation – or
• globally for a complete namespace using \nn\rest::Endpoint()->register() in the ext_localconf.php of your extension.

You should decide using one of both, depending on your individual architecture.

1. Alternative 1: Registering an Endpoint using Annotations

   Simply add the @Api\Endpoint() Annotation to the comment block above your class. The nnrestapi will automatically parse the DocComment and register your endpoint.

   You can find out more on this page.

   <?php
   
   namespace My\Extension\Api;
   
   use Nng\Nnrestapi\Annotations as Api;
   use Nng\Nnrestapi\Api\AbstractApi;
   
   /**
    * @Api\Endpoint()
    */
   class Example extends AbstractApi
   {
     // Your methods
   }

   Copied!

2. Alternative 2: Global registry of a namespace

   In your ext_localconf.php you can let nnrestapi automatically register all endpoints in a certain namespace.

   Example: If all of your Endpoints are in the namespace My\Extension\Api\* then you could have them all automatically registered by adding this code to your ext_localconf.php.

   // Register path to my endpoints		
   \nn\rest::Endpoint()->register([
       'namespace' => 'My\Extension\Api'
   ]);

   Copied!

   By registering a global namespace for all your endpoints you can now dismiss the @Api\Endpoint() Annotation in the DocComment of your class:

   <?php
   
   namespace My\Extension\Api;
   
   use Nng\Nnrestapi\Annotations as Api;
   use Nng\Nnrestapi\Api\AbstractApi;
   
   /**
    * Nothing needed here :)
    */
   class Example extends AbstractApi
   {
     // Your methods
   }

   Copied!

The class- and method-name are the key! 

The nnrestapi has a standardized way to route a request to a controller and method.

Let's look at the following two URL examples:

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

If no custom routing was defined, nnrestapi will interpret the URL parts like this:

https://www.mywebsite.com/api/{className}/{methodName}/{uid}/{param1}/{param2}/{param3}/{param4}

Only exception: If an integer (number) was passed as {methodName} (like in the second line of the example above), the request will be routed to the index-method of your class. In this case, the parts of the URL will be interpreted like this:

https://www.mywebsite.com/api/{className}/{uid}/{param1}/{param2}/{param3}/{param4}

Defining custom URL paths 

In certain cases, you might want to define a custom routing instead of using the Routing by method-name

This can be accomplished using this annotation:

@Api\Route("/your/custom/url")

The Annotation gets placed in the comment above the method of your Api class. Here is a full example:

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Route("GET /test/route")
    * @Api\Access("public")
    * 
    * @return array
    */
   public function customRoutingTest()
   {
      return ['message'=>'Hello!'];
   }
}

When using custom routing, the method name is irrelevant and does not have to follow the pattern {request_method}{Classname}Action.

The above method customRoutingTest() would be executed when sending a GET Request to

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

Want to find out more? 

Please refer to the @Api\Route section of this documentation for more details and examples.

Accessing Request variables in your endpoint 

When a request is forwarded to your endpoint, nnrestapi automatically injects an instance of Nng\Nnrestapi\Mvc\Request. This is basically a simple wrapper for the standard TYPO3 TYPO3\CMS\Extbase\Mvc\Request, pimped with a couple of features needed specifically for accessing the Request-body (the parsed JSON), the files passed in the multipart-formdata etc.

To make things intuitive for anybody who is familiar with the TYPO3 ActionControllers, you can access the Nng\Nnrestapi\Mvc\Request in the class property $this->request.

This section gives you an overview of common variables you might want to access while evaluating the request and composing the response.

All the following examples are placed inside your endpoints' method.

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Access("public")
    * 
    * @return array
    */
   public function getIndexAction()
   {
      $args = $this->request->getArguments();
      return $args;
   }
}

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Access("public")
    * 
    * @return array
    */
   public function getNewsAction()
   {
      $args = $this->request->getArguments();
      return $args;
   }
}

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

https://www.mysite.com/api/{class}/{method}/{uid}/{param1}/{param2}/{param3}/{param4}

/**
 * @Api\Route("GET /example/{name}")
 * @Api\Access("public")
 * 
 * @param string $name
 * @return array
 */
public function anyMethodNameYouLike( $name = null )
{
   return ['welcome' => "Welcome {$name} to my RestAPi!"];
}

How to send a response from your endpoint 

Your Api can return almost anything. The nnrestapi extension will take care of converting your return value to a JSON, no matter if you pass a simple array, a Domain Model or an ObjectStorage.

If no other response header or status code is specified, the nnrestapi will create all headers for a 200 OK HTTP Response. It will also automatically send the correct CORS and Credential-headers like Access-Control-Allow-Credentials etc.

Check this section to see all default headers generated and find out how to remove or add custom headers to the response.

Returning an Array 

The most basic return value is an array:

<?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!'];
   }
}

If you open the URL https://www.youwebsite.com/api/test/example in your browser, you will see this JSON response:

{"result":"welcome!"}

Returning a Domain Model 

You can also return a Model as response from your method:

public function getExampleAction()
{
   $model = $this->exampleRepository->findByUid( 123 );
   return $model;
}

In the result the model will be automatically converted to a JSON-object. Even relations like SysFileReferences or other models and objects get converted.

{"uid":123, "title":"nice!", "image":{"publicUrl":"path/to/some/image.jpg", "title":"..."}}

plugin.tx_nnrestapi.settings.globalDistillers {
   My\Extension\Extbase\Domain\Model\Example {
      flattenFileReferences = 1
   }
}

{"uid":123, "title":"nice!", "image":"path/to/some/image.jpg"}

Returning an ObjectStorage 

If you return an ObjectStorage, e.g. with multiple Domain Models - or SysFileReferences, the ObjectStorage will automatically be converted to an array:

public function getExampleAction()
{
   $allExamples = $this->exampleRepository->findAll();
   return $allExamples;
}

The result will be an array of Objects:

[
   {"uid":1, "title":"One", "image":{"publicUrl":"one.jpg"}},
   {"uid":2, "title":"Two", "image":null},
   {"uid":3, "title":"Three", "image":{"publicUrl":"three.jpg"}}
]   

Example: Get list of all countries 

Here are a few examples using the EXT:nnhelpers which can make life a lot easier when fetching data from the database.

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

Example: Return TypoScript-Setup 

/**
 * Get TypoScript settings for given plugin
 *
 * @Api\Access("public")
 * @return array
 */
public function getSettingsAction()
{
   $settings = \nn\t3::Settings()->get('myextname');
   return $settings;
}

Example: Returning MANY rows of data 

Sometimes – especially when retrieving many Object from a database table, the standard DataMapper of TYPO3 can be extremely slow. If there is no need to fetch relations, but simple get the raw data array from the database, this recipe will speed things up:

/**
 * the fastest way to get massive amount of data from database and return it as JSON
 *
 * @Api\Access("public")
 * @return array
 */
public function getBiglistAction()
{
   $rows = \nn\t3::Db()->findAll('tx_myext_domain_model_example');
   return $rows;
}

Responding with an Error 

The nnrestapi has a few shortcuts built in to respond with error codes, if the request parameters were invalid or the requested data could not be retrieved.

Have a look at the class Nng\Nnrestapi\Mvc\Response to see all available options.

Here we are checking for a model. If it can't be found, we return a 404 NOT FOUND error:

<?php   
namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Test extends AbstractApi 
{
   /**
    * Call via GET-request with an uid: https://www.mywebsite.com/api/test/1 
    *
    * @Api\Access("public")
    * @return array
    */
   public function getIndexAction( $uid = null )
   {
      $entry = $this->entryRepository->findByUid( $uid );
      if (!$entry) {
         return $this->response->notFound('Model with uid [' . $uid . '] was not found.');
      }
      return $entry;
   }
}

If you open the URL https://www.mywebsite.com/api/test/1 in your browser and pass the uid of an entry that does not exist, you will see the following JSON response. It will be sent with a 404 NOT FOUND header:

{"status":404, "error":"Model with uid [1] was not found."}

Responding by throwing an Error 

An alternative way to respond with an Error is by throwing an Nng\Nnrestapi\Error\ApiError. This allows adding a custom error code, e.g. for better evaluating and displaying / localizing the error in your frontend application.

To immediatly throw the ApiError and abort further processing, you can use the \nn\rest::Error()-Helper:

// basic syntax
\nn\rest::Error( $message, $httpErrorCode, $myCustomErrorCode );

// examples
\nn\rest::Error( 'Nothing here, bro.', 404, 'ERROR.NOTHING' );
\nn\rest::Error( 'Not your district, bro.', 403, 1234567 );

The last example above will send a 403 Unauthorized header and a JSON with the message and custom error code:

{"status":403, "error":"Not your district, bro.", "code":123567}

Full example

<?php   
namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Test extends AbstractApi 
{
   /**
    * Call via GET-request with an uid: https://www.mywebsite.com/api/test 
    *
    * @Api\Access("public")
    * @return array
    */
   public function getIndexAction()
   {
      if ($this->someCheckFailed()) {
         \nn\rest::Error( 'the check failed', 403, 612523 );
      }

      return ['everything'=>'fine'];
   }
}

Overview of error codes 

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: 

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'];
}

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

Mark a class as endpoint for the TYPO3 RestAPi 

There are two basic ways to register a Class as endpoint so the extension will route requests to it:

• by using the nnrest::Endpoint()->register() method in the ext_localconf.php of your extension. This is useful to register all Classes in a certain namespace, e.g. My\Extension\Api\*.
• By using the @Api\Endpoint() Annotation in the DocComment of the individual Class as described in this chapter.

Marking individual Classes as Endpoint 

In the following example we will mark the class Example as an TYPO3 RestApi Endpoint by setting the @Api\Endpoint() Annotation in the comment block above the class.

Requests sent to https://www.yourwebsite.com/api/example/... will automatically be routed to this class.

Here is a full example

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   // Your methods
}

The above endpoint can be reached over the URL:

https://www.mywebsite.com/api/example/...

Override the path segment / class name 

By default, the first path segment after api/.../ is identical with the class name of your endpoint. If your class is named Example, then you can route the requests to it by calling the URL api/example/.

This can be overridden by setting a value in @Api\Endpoint("name").

In the following example, we would like to route requests to api/apples/... to the class Oranges. This can be achieved by setting @Api\Endpoint("apples"):

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint("apples")
 */
class Oranges extends AbstractApi
{
   // Your methods
}

The above endpoint can be reached over the URL:

https://www.mywebsite.com/api/apples/...

Restricting access to your endpoint 

The @Api\Access() annotation can be used to restrict the access to an endpoint to certain ...

• Frontend-Users (fe_users)
• Frontend-User-Groups (fe_user_groups)
• Api-Users (defined in the Extension Manager)
• Backend-Users or Admins
• IP-adresses

The basic syntax is:

@Api\Access("options")

Full example:

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * Only Frontend-Users will be able to access this endpoint
    *
    * @Api\Access("fe_users")
    * @return array
    */
   public function getIndexAction() 
   {
      return ['nice'=>'works!'];
   }
}

Examples and details? 

Pleaser check out the section "how to restrict access" for detailed information and examples.

Disabling automatic merging of JSON data with a Model 

The @Api\AutoMerge() annotation can be used to control, if the JSON data automatically gets merged with the Model you have defined as argument injection in your endpoint.

By default, autoMerge is enabled. This can be changed by setting the following flag in the TypoScript setup:

plugin.tx_nnrestapi.settings {
   autoMerge.enabled = 0
}

The default setting in TypoScript can be overriden for every endpoint individually by using the following Annotation syntax:

// Merge data with model (same as TRUE)
@Api\AutoMerge()

// Merge data with model
@Api\AutoMerge(TRUE)

// Disable the merging of data
@Api\AutoMerge(FALSE)

Full example:

<?php

namespace My\Extension\Api;

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

use My\Extension\Domain\Model\Article;

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * Disable merging of JSON data with the model
    *
    * @Api\Route("PUT /news/{article}")
    * @Api\Example("{'title':'My new title'}")
    * @Api\AutoMerge(FALSE)
    * @Api\Access("public")
    *
    * @param Article $article
    * @return array
    */
   public function getIndexAction( Article $article = null ) 
   {
      return $article;
   }
}

\nn\t3::Db()->update( $article )

$modifiedArticle = \nn\t3::Obj( $article )->merge(['title'=>'new title', ...]);

Enable caching for a TYPO3 RestAPi endpoint 

If the method of an endpoint has the @Api\Cache annotation set, then its result will be cached. The next time this endpoint is called, the result will be retrieved from the cache without calling the method.

Useful, if static data should be loaded like settings, dropdown-values or country-lists etc. The cache will only be cleared and rebuilt, if the "clear cache" button is clicked in the backend.

The syntax is:

@Api\Cache

Here is a full example:

<?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;
   }

}

Handling the cache yourself 

In case you would like to handle the caching of data yourself, the nnhelpers Cache-methods are very useful. Here is a basic example – have a look at the nnhelpers documentation for more info:

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */   
class Example extends AbstractApi
{
   /**
    * @Api\Access("public")
    *
    * @return array
    */
   public function getAllAction() 
   {
      $cacheIdentifier = 'example';

      if ($cache = \nn\t3::Cache()->get($cacheIdentifier)) {
         return $cache;
      }

      $result = $this->someComplicatedOperation();
      return \nn\t3::Cache()->set($cacheIdentifier, $result);
   }

}

Dehydrate the JSON-result before returning it to the client 

By default, any Array, Object, Model or ObjectStorage returned by your endpoint method will be recursively converted to an array and then sent as JSON response to the client.

In certain cases you might want to remove certain fields from the JSON, e.g. to protect sensitive data to be passed to the frontend or to reduce the complexity or depth of the returned JSON.

There are two ways to solve this:

• Write a custom Distiller to post-process the array before it is returned to the frontend.
• Define global Distillers on a per-model base using the TypoScript setup.

@Api\Distiller( \My\Extension\Distiller\Name::class )

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */	
class Example extends AbstractApi
{
   /**
    * @Api\Distiller( \My\Extension\Distiller\RemovePassword::class )
    * @Api\Access("public")
    *
    * @return array
    */
   public function getIndexAction() 
   {
      $user = $this->getUserExample();
      return $user;
   }

}

<?php

namespace My\Extension\Distiller;

use Nng\Nnrestapi\Distiller\AbstractDistiller;

class RemovePassword extends AbstractDistiller {

   /**
    * @return void
    */
   public function process( &$data = [] ) {
      unset($data['password']);
   }

}

<?php

namespace My\Extension\Distiller;

use Nng\Nnrestapi\Distiller\AbstractDistiller;

class RemoveAlmostEverything extends AbstractDistiller {

   /**
    * @var array
    */
   public $keysToKeep = ['uid', 'username'];

}

// Deep array: Properties of nested array are returned. Key is returned in dot-syntax 
public $keysToKeep = ['uid', 'images', 'title', 'images.0.publicUrl'];

// Associative array: Get deep nested property and map it to a new key
public $keysToKeep = ['uid'=>'uid', 'publicUrl'=>'images.0.publicUrl'];

// Mixture is also possible
public $keysToKeep = ['uid', 'title', 'publicUrl'=>'images.0.publicUrl'];

plugin.tx_nnrestapi.settings {

   # Fields to remove from Model when converting to array
   globalDistillers {

      My\Extension\Extbase\Domain\Model\Example {
         exclude = parent, mktime, crdate
      }

      TYPO3\CMS\Extbase\Domain\Model\FileReference {
         exclude = uidLocal, crop, publicUrl, type
      }
   }
}

plugin.tx_nnrestapi.settings.globalDistillers {
   My\Extension\Extbase\Domain\Model\Example {
      exclude = parent, mktime, crdate
   }
}

plugin.tx_nnrestapi.settings.globalDistillers {
   My\Extension\Extbase\Domain\Model\Example {
      include = uid, title, image
   }
}

// PUT or PATCH to /api/entry/{uid}
{"title":"New title"}

plugin.tx_nnrestapi.settings.globalDistillers {
   My\Extension\Extbase\Domain\Model\Example {
      flattenFileReferences = 1
   }
}

{"image":{"publicUrl":"path/to/file.jpg", "title":"...", "crop":"..."}}

{"image":"path/to/file.jpg"}

{"image":NULL}

Add example data to your documentation 

The purpose of this annotation is to add example data to the automatically generated documentation in the TYPO3 backend module of the nnrestapi that can be used for composing requests using the test bed.

This annotation has no other function in the frontend. It is just to make working with the backend-module easier: The extension comes shipped with a test bed to send and test your requests directly in the backend module. The example data will appear in the documentation and can be used to compose your request.

Example data for setting a string in the body:

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

Example data for creating a JSON-request.

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

Here is a full example:

<?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'];
   }

}

Don't forget that you can always use Markdown in your documentation.

Here is an example:

/**
 * ## 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
 */

The above example would automatically create this documentation in the backend module:

Add custom label to backend module 

This Annotation will override the default label that is used in the collapsible elements of the RESTApi backend module. By default, the extension generates this label by evaluating the default or custom routing.

This annotation has no other function in the frontend. It is just for modifying the view in the backend-module and making the labels of the endpoints better legible or for handling edge cases.

|

The syntax is:

@Api\Label("this is my label!")

Here is a full example:

<?php

namespace My\Extension\Api;

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

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

}

Enable or disable logging for an endpoint 

The @Api\Log() annotation can be used to explicitly enable or disable logging of requests to a specific endpoint. Logged requests are saved in the database table nnrestapi_log and can be viewed in the backend module.

For a complete overview of the logging system, see Logging.

This is useful when:

• You want to disable logging for endpoints that are called frequently (e.g., health checks, polling)
• You want to force enable logging for specific endpoints regardless of global settings
• You need to debug specific endpoints by enabling logging temporarily

The syntax is:

@Api\Log(true)    // Enable logging for this endpoint
@Api\Log(false)   // Disable logging for this endpoint
@Api\Log()        // Same as true

Full example:

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * This endpoint will NEVER be logged, unless `loggingMode` 
    * was set to "force" in the Extension Manager.
    * 
    * Useful for high-frequency endpoints like health checks.
    *
    * @Api\Log(false)
    * @Api\Access("public")
    * @return array
    */
   public function getHealthAction() 
   {
      return ['status' => 'ok'];
   }

   /**
    * This endpoint will be logged, if:
    * - custom logging is enabled in the Extension Manager
    * - AND the `loggingMode` was set to "explicit" or "force"
    *
    * @Api\Log(true)
    * @Api\Access("fe_users")
    * @return array
    */
   public function postSensitiveAction() 
   {
      return ['result' => 'logged'];
   }
}

Logging behavior overview 

Global logging settings 

The global logging behavior can be configured in the Extension Manager settings:

• Logging enabled: Enable/disable logging globally

• Logging mode: Controls how the @Api\Log() annotation is interpreted:

  • all: Log all requests, except those with @Api\Log(false)
  • explicit: Only log requests that have @Api\Log() or @Api\Log(true)
  • force: Log all requests, ignoring any @Api\Log() annotations
• Error logging: Log errors and exceptions
• Auto-clear logs: Automatically remove old log entries after X days

See the Configuration section for more details on global settings.

Sends Cache-Control headers for a TYPO3 RestAPi endpoint 

With the default settings of nnrestapi, the client-side cache will be disabled by sending the default Cache-Control: no-cache and Paragma headers.

If the data doesn't change very often, it doesn't make sense for the client to keep requesting the same data from the endpoint. By sending an appropriate Cache-Control header you can tell the client how many seconds it should use data stored in the local cache before sending the next request to the Api.

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

The syntax is:

@Api\MaxAge( seconds )

Here is a full example:

<?php

namespace My\Extension\Api;

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

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

}

Handling the Cache-Control header yourself 

If you would like to send the Cache-Control headers from inside of your method, you can use $this->response->setMaxAge( $seconds ).

You can also add, modify or remove any other default header sent by the nnrestapi by calling $this->response->addHeader( $headerArray ). More information can be found in this chapter

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */   
class Example extends AbstractApi
{
   /**
    * @Api\Access("public")
    *
    * @return array
    */
   public function getAllAction() 
   {
      $this->response->setMaxAge( 100 );

      $result = $this->someComplicatedOperation();
      return \nn\t3::Cache()->set($cacheIdentifier, $result);
   }

}

Retrieve hidden records and relations from the database. 

This makes the TYPO3 Frontend behave like the Typo3 Backend: Hidden records and records with fe_group or starttime/endtime-restrictions will be returned to the frontend, although they usually would only be visible in the TYPO3 backend for admins.

The syntax is:

@Api\IncludeHidden("tablename")

Overview of options 

You can pass the tablename(s) or modelnames to @Api\IncludeHidden(...):

Example 

Here is a full example:

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */   
class Example extends AbstractApi
{
   /**
    * @Api\IncludeHidden
    * @Api\Access("public")
    *
    * @return array
    */
   public function getAllAction() 
   {
      return $this->someRepository->findAll();
   }

}

If you would like to handle the access to hidden records yourself, you can use the \nn\rest::Settings()->setIgnoreEnableFields() helper before retrieving your data from the repository.

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Access("public")
    *
    * @return array
    */
   public function getAllAction() 
   {
      if ($this->yourOwnCheckMethod()) {
         // ignore hidden restrictions for ALL tables
         \nn\rest::Settings()->setIgnoreEnableFields( true );
         // ignore hidden restrictions for certain tables
         // \nn\rest::Settings()->setIgnoreEnableFields(['tt_content', 'my_table_name']);
      }
      return $this->someRepository->findAll();
   }

}

Control how your TYPO3 RestAPi renders the JSON result 

| Options and settings for converting the response-data to JSON. Currently, only depth is implemented.

With depth you can control, how deep the returned object will be parsed when it is converted to the JSON-array.

This is helpful, if you are returning Objects with many nested relations or recursions, but you only need the first few levels of the data in the frontend.

The syntax is:

@Api\Json(depth=4)

Here is a full example:

<?php

namespace My\Extension\Api;

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

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

}

Use custom routing for your TYPO3 RestAPI endpoint 

The @Api\Route annotation allows you to define custom URLs (Routes) to your endpoint and define the order of arguments passed to your method. It is very similar to the Symfony Routing syntax.

A basic example would be:

@Api\Route("/your/custom/url")

After clearing the cache, the method that has this annotation will be reachable at the URL: https://www.yourwebsite.com/api/your/custom/url.

By using custom Routing, the method name can be whatever you like – you don't not have to use the standard method-name {requestMethod}{pathPart}Action()

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Route("/your/custom/url")
    * @Api\Access("public")
    *
    * @return array
    */
   public function anyMethodNameYouLike() 
   {
      return ['nice'=>'result'];
   }

}

nnrestapi:
   routing:
      basePath: '/api'

// https://www.mywebsite.com/api/test/demo/123
@Api\Route("/test/demo/{uid}") 

// https://www.mywebsite.com/api/test/demo/123/whatever
@Api\Route("/test/demo/{uid}/{test}")

// https://www.mywebsite.com/api/test/demo/123
// https://www.mywebsite.com/api/test/demo
@Api\Route("/test/demo/{uid?}")

// https://www.mywebsite.com/api/test/demo/123/456
// https://www.mywebsite.com/api/test/demo/123
// https://www.mywebsite.com/api/test/demo
@Api\Route("/test/demo/{uid?}/{test?}")

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
   * @Api\Route("GET /test/route/{name}")
   * @Api\Access("public")
   * 
   * @return array
   */
   public function customRoutingTest( $name = null )
   {
      return ['message'=>"Hello, {$name}!"];
   }
}

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */   
class Example extends AbstractApi
{
   /**
    * @Api\Route("GET /test/route/{name}")
    * @Api\Access("public")
    * 
    * @return array
    */
   public function customRoutingTest()
   {
      $args = $this->request->getArguments();
      return ['message'=>"Hello, {$args['name']}!"];
   }
}

// listen to ALL requests (GET, POST, PUT, DELETE, PATCH)
@Api\Route("/test/demo/something")

// only listen to GET requests
@Api\Route("GET /test/demo/something")

// listen to GET, POST and PUT requests
@Api\Route("GET|POST|PUT /test/demo/something")

// listen to GET and parse URL parameters
@Api\Route("GET /auth/log_me_out/{uid}/{something}")

Check incoming request for SQL Injections 

The @Api\Security\CheckInjections() annotation allows you perform a very basic check of the incoming POST and GET variables. It searches for typical SQL-injection patterns like "; SELECT ... and automatically locks all requests from the current IP for 24 hours.

We know this: checking for typical SQL injection patterns at this level is not very reliable. There are many sneaky methods and patterns that could be missed by this check. And it should never be be a substitute for securing your database queries and sanitizing the variables before writing them to the database.

On the other hand: have you ever had a look in one of your server log files? You will see tons of requests from bots using patterns that would be successfully blocked by using this annotation. And keeping bots out of the system as soon as possible is always sensible.

The basic syntax is:

@Api\Security\CheckInjections( $autoLockIp )

An example would be:

// Check for typical injection-patterns and lock IP if an attempt was detected
@Api\Security\CheckInjections()

// Check, but don't automatically lock the IP
@Api\Security\CheckInjections( false )

Full example:

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * (!) Note that we also need to add CheckLocked() for this to work
    * This could also be done globally in the TypoScript setup
    *
    * @Api\Security\CheckInjections()
    * @Api\Security\CheckLocked()
    * @Api\Access("public")
    *
    * @return array
    */
   public function getSettingsAction() 
   {
      return ['nice'=>'result'];
   }

}

Globally activating an injection test 

If you would like to globally check for SQL injections for every endpoint, you do to not need to add @Api\Security\CheckInjections() to every endpoint manually. Instead you can set up a global check using this TypoScript setup:

plugin.tx_nnrestapi {
   settings {
      security {
         defaults {
            10 = \Nng\Nnrestapi\Utilities\Security->checkInjections
            20 = \Nng\Nnrestapi\Utilities\Security->checkLocked
         }
      }
   }
}

// manually lock an IP for 5 minutes
\nn\rest::Security( $this->request )->lockIp( 300, 'Reason why...' );

// unlock the IP
\nn\rest::Security( $this->request )->unlockIp();

Check if IP was locked 

This annotation will check, if the current IP was blocked by a previous security check.

Use this annotation like this:

@Api\Security\CheckLocked()

(Un)locking an IP manually 

The \nn\rest::Security()-Helper has many useful methods in case you would like to lock the users manually.

Have a look at \Nng\Nnrestapi\Utilities\Security for more details.

// manually lock an IP for 5 minutes
\nn\rest::Security( $this->request )->lockIp( 300, 'Reason why...' );

// unlock the IP
\nn\rest::Security( $this->request )->unlockIp();

plugin.tx_nnrestapi {
   settings {
      security {
         defaults {
            10 = \Nng\Nnrestapi\Utilities\Security->checkInjections
            20 = \Nng\Nnrestapi\Utilities\Security->checkLocked
         }
      }
   }
}

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Security\CheckLocked()
    * @Api\Access("public")
    *
    * @return array
    */
   public function getSettingsAction() 
   {
      return ['nice'=>'result'];
   }

}

Limiting number of requests to an endpoint 

This annotation allows you limit the number of request to an endpoint per minute from the current IP-address.

The basic syntax is:

@Api\Security\MaxRequestsPerMinute( $limit, $identifier )

An example would be:

// Limit access to all endpoints with "my_id" to 10 per IP and minute
@Api\Security\MaxRequestsPerMinute( 10, "my_id" )

// Limit overall access to all endpoints using this annotation to 10 per IP and minute
@Api\Security\MaxRequestsPerMinute( 10 )

Exceeding the given number will result in an 403 Error response.

The optional argument my_id can be any arbitrary key.

• When using the same key in multiple endpoints, all endpoint calls with the same key will be counted
• Without an id, all endpoints using the annotation will be counted

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Security\MaxRequestsPerMinute(5, "getSettings")
    * @Api\Access("public")
    *
    * @return array
    */
   public function getSettingsAction() 
   {
      return ['nice'=>'result'];
   }

}

// returns FALSE if IP has exceeded number of requests for `my_key`
$isBelowLimit = \nn\rest::Security( $this->request )->maxRequestsPerMinute(['my_key'=>60]);

// manually lock an IP for 5 minutes
\nn\rest::Security( $this->request )->lockIp( 300, 'Reason why...' );

// unlock the IP
\nn\rest::Security( $this->request )->unlockIp();

Reverse Proxy Configuration 

If your TYPO3 installation is behind a reverse proxy (e.g., nginx, load balancer, CDN), the client's real IP address is typically forwarded in headers like X-Forwarded-For instead of being available in REMOTE_ADDR.

Without proper configuration, all requests would appear to come from the same IP (the proxy's IP), causing rate limiting to affect all users collectively.

The nnrestapi uses TYPO3's NormalizedParams to determine the client IP, which respects TYPO3's reverse proxy configuration. To enable this, configure the following settings in your config/system/settings.php (in composer-based installations) and typo3conf/LocalConfiguration.php in non-composer-based installations:

// IP address(es) of your reverse proxy
$GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyIP'] = '10.0.0.1';

// For multiple proxies, use comma-separated list
$GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyIP'] = '10.0.0.1,10.0.0.2';

// Which IP to use from X-Forwarded-For header: 'first' or 'last'
// 'first' = original client (recommended for most setups)
// 'last' = last proxy before TYPO3
$GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyHeaderMultiValue'] = 'first';

Control where files are uploaded to in your TYPO3 RestAPi 

With the @Api\Upload(...) annotation you can control, where the file uploads of a multipart/form-data request are moved to.

The syntax is:

@Api\Upload( option )

Where option can have one of the following expressions to either define a direct file path, a custom Class to return the upload-path or the key to a configuration in the TypoScript setup:

The Annotation is placed in the comment block above your method / endpoint:

<?php

namespace My\Extension\Api;

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

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

}

Let’s have a look at the configuration in TypoScript setup for plugin.tx_nnrestapi.settings.fileUploads:

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

      // target-path for file, file-0, file-1, ...
      file = 1:/api/tests/
   }		
}

Make sure the upload-folder exists and has the correct rights for reading/writing.

return ['defaultStoragePath'=>'1:/my/custom/path']

return ['file'=>'1:/files/', 'image-0':'1:/images/', ...];

<?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') . '/'
      ];
   }

}

plugin.tx_nnrestapi.settings.fileUploads {
   monthdate {
      pathFinderClass = My\Extension\Helper\UploadPathHelper::getPathForDate
   }		
}

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Upload("config[monthdate]")
    * @Api\Access("public")
    *
    * @param \My\Extension\Domain\Model\ApiTest $apiTest
    * @return array
    */
   public function getAllAction( $apiTest = null ) 
   {
      return $apiTest;
   }

}

Encrypt uploaded files on-the-fly 

The @Api\Upload\Encrypt() annotation allows encrypting uploaded files on-the-fly before they are stored on the server. This can be useful for sensitive documents that need to be protected at rest.

The syntax is:

@Api\Upload\Encrypt("default")
@Api\Upload\Encrypt("config[keyname]")

The value "default" refers to the default encryption configuration defined in TypoScript. You can also use "config[keyname]" to reference a custom configuration.

Full example:

<?php

namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class Document extends AbstractApi
{
   /**
    * Upload and encrypt a sensitive document.
    *
    * @Api\Upload("1:/secure-uploads/")
    * @Api\Upload\Encrypt("default")
    * @Api\Access("fe_users")
    * @return array
    */
   public function postSecureAction() 
   {
      $files = $this->request->getUploadedFiles();
      return ['uploaded' => count($files)];
   }
}

How it works 

When a file is uploaded with encryption enabled:

1. The file is renamed to include a .enc marker (e.g., filename.enc.jpg)
2. The file content is encrypted using AES encryption with an initialization vector (IV)
3. The IV is stored at the beginning of the encrypted file
4. The original file is replaced with the encrypted version

Encrypted files can only be decrypted using the same encryption key.

Configuration 

The encryption is configured via TypoScript. The default configuration is:

plugin.tx_nnrestapi.settings.fileUploadEncrypt {
   default {
      # Class with methods for encrypting / decrypting files
      encryptionClass = Nng\Nnrestapi\Helper\UploadEncryptHelper

      # Number of 16-byte blocks to read/write at a time (default: 255)
      fileEncryptionBlocks = 255

      # Cipher algorithm (AES-128-CBC or AES-256-CBC)
      cipher = AES-128-CBC
   }
}

Custom encryption configurations 

You can define multiple encryption configurations in TypoScript:

plugin.tx_nnrestapi.settings.fileUploadEncrypt {
   default {
      encryptionClass = Nng\Nnrestapi\Helper\UploadEncryptHelper
      cipher = AES-128-CBC
   }
   highSecurity {
      encryptionClass = Nng\Nnrestapi\Helper\UploadEncryptHelper
      cipher = AES-256-CBC
   }
}

Then reference them in your annotation:

@Api\Upload\Encrypt("config[highSecurity]")

Custom encryption class 

You can create your own encryption class by extending AbstractUploadEncryptHelper. This allows you to implement custom encryption algorithms or integrate with external encryption services.

Step 1: Create your custom encryption class

<?php
namespace My\Extension\Helper;

use Nng\Nnrestapi\Helper\AbstractUploadEncryptHelper;
use TYPO3\CMS\Core\Http\UploadedFile;

class MyEncryptHelper extends AbstractUploadEncryptHelper
{
   /**
    * Rename the file before it is moved to the target folder.
    * Use this to add markers like `.enc` to the filename.
    *
    * @param string $filename Original filename
    * @param string $targetPath Target folder path
    * @param UploadedFile $file The uploaded file object
    * @return string The new filename
    */
   public function getFilename($filename, $targetPath, $file) 
   {
      $suffix = pathinfo($filename, PATHINFO_EXTENSION);
      return uniqid() . '.encrypted.' . $suffix;
   }

   /**
    * Encrypt the file after it has been moved to the target folder.
    *
    * @param string $filename Path to the file (relative to site root)
    * @param string $targetPath Target folder path
    * @param UploadedFile $fileObj The uploaded file object
    * @return void
    */
   public function encrypt($filename, $targetPath, $fileObj) 
   {
      $absPath = \nn\t3::File()->absPath($filename);
      $content = file_get_contents($absPath);
      
      // Your encryption logic here
      $encrypted = $this->myEncryptionMethod($content);
      
      file_put_contents($absPath, $encrypted);
   }

   /**
    * Decrypt a file. Writes the decrypted content to a temporary destination file.
    * This method is called when serving encrypted files to the user.
    *
    * Note: Uses file streams to support large files without memory issues.
    *
    * @param string $sourcePath Path to the encrypted file
    * @param string $destPath Path where decrypted file should be written (temp file)
    * @return bool
    */
   public function decrypt($sourcePath, $destPath) 
   {
      $fpIn = $this->openSourceFile($sourcePath);
      $fpOut = $this->openDestFile($destPath);
      
      // Read, decrypt and write in chunks for large file support
      while (!feof($fpIn)) {
         $chunk = fread($fpIn, 8192);
         $decrypted = $this->myDecryptionMethod($chunk);
         fwrite($fpOut, $decrypted);
      }
      
      fclose($fpIn);
      fclose($fpOut);
      
      return true;
   }

   private function myEncryptionMethod($data) 
   {
      // Implement your encryption
      return $data;
   }

   private function myDecryptionMethod($data) 
   {
      // Implement your decryption
      return $data;
   }
}

Step 2: Register your class in TypoScript

plugin.tx_nnrestapi.settings.fileUploadEncrypt {
   myCustomEncryption {
      encryptionClass = My\Extension\Helper\MyEncryptHelper
      
      # You can pass additional configuration options
      # They will be available in $this->configuration
      myCustomOption = someValue
   }
}

Step 3: Use the annotation in your endpoint

<?php
namespace My\Extension\Api;

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

/**
 * @Api\Endpoint()
 */
class SecureDocument extends AbstractApi
{
   /**
    * Upload a file with custom encryption.
    *
    * @Api\Upload("1:/secure-documents/")
    * @Api\Upload\Encrypt("config[myCustomEncryption]")
    * @Api\Access("fe_users")
    * @return array
    */
   public function postUploadAction() 
   {
      $files = $this->request->getUploadedFiles();
      return ['success' => true, 'files' => count($files)];
   }
}

public function encrypt($filename, $targetPath, $fileObj) 
{
   // Access your custom TypoScript options
   $myOption = $this->configuration['myCustomOption'] ?? 'default';
   
   // Use it in your encryption logic
   // ...
}

Enable/disable localization (translation) of data 

The @Api\Localize() annotation can be used to force or disable the localization of models and entries retrieved from the database.

It allows overriding the default settings defined in the TypoScript setup.

By default localization is disabled. This can be changed by setting the following flag in the TypoScript setup:

plugin.tx_nnrestapi.settings {
    localization.enabled = 1
}

The basic syntax of @Api\Localize() is:

@Api\Localize()
@Api\Localize(TRUE)
@Api\Localize(FALSE)

Full example:

namespace My\Extension\Api;

use Nng\Nnrestapi\Annotations as Api;
use Nng\Nnrestapi\Api\AbstractApi;
 
/**
 * @Api\Endpoint()
 */
class Example extends AbstractApi
{
   /**
    * @Api\Localize()
    * @Api\Access("public");
    * @return array
    */
    public function getIndexAction() {
        return ['this'=>'works!'];
    }
}

   
/**
 * @Api\Localize(TRUE)
 */

   
/**
 * @Api\Localize()
 */

   
/**
 * @Api\Localize(FALSE)
 */

Adding custom annotations to your TYPO3 RestApi endpoints 

If you would like to add custom annotations that get parsed and passed to the endpoint, then follow these steps.

1. Create a class for the annotation

   Create a file in your own extension under Classes/Annotations/Example.php.

   Important: The class needs to have the @Annotation in the class comment.

    
   <?php
   
   namespace My\Ext\Annotations;
   use Nng\Nnrestapi\Api\AbstractApi;
   
   /**
    * @Annotation
    */
   class Example extends AbstractApi
   {
      public $value;
   
      /**
       * Normalize parameter to array.
       * Only needed, if you allow single AND multiple arguments in your annotation.
       *
       */
      public function __construct( $arr ) 
      {
         $this->value = is_array( $arr['value'] ) ? $arr['value'] : [$arr['value']];
      }
     
      /**
       * This method is called when parsing all classes.
       * You must implement it in your own Annotation, if you want the parsed 
       * data to be cached and accessible later in your endpoint.
       *
       */
      public function mergeDataForEndpoint( &$data ) 
      {
         $data['myIdentifer'] = $this->value;
      }
   }

   Copied!

2. Use the annotation in your endpoint

   Make sure to reference your namespace.

    
   <?php
   
   namespace My\Ext\Api;
   
   use My\Ext\Annotations as MyApi;
   use Nng\Nnrestapi\Annotations as Api;
   
   /**
    * @Api\Endpoint()
    */
   class Test 
   {
      /**
       * @MyApi\Example("somevalue")
       * @Api\Access("public")
       * @return array
       */
      public function getAllAction()
      {	
         $endpoint = $this->request->getEndpoint();
         \nn\t3::debug( $endpoint );
         die();
      }
   }

   Copied!

3. Access the annotation value

   You have access to the value of your annotation at several places.

   Here is an example that accesses the above annotation value in the checkAccess method: See @Api\Access(...) for details.

    
   <?php
   
   namespace My\Ext\Api;
   
   use My\Ext\Annotations as MyApi;
   use Nng\Nnrestapi\Annotations as Api;
   
   /**
    * @Api\Endpoint()
    */
   class Test
   {
      /**
       * @return boolean
       */
      public function checkAccess( $endpoint = [] ) {
         if ($values = $endpoint['myIdentifer'] ?? false) {
            if (in_array('locked', $values)) {
               return false;
            }
         }
         return true;
      }
   
      /**
       * @MyApi\Example("locked")
       * @return array
       */
      public function getAllAction()
      {	
         // ...
      }
   }

   Copied!

Only allow certain users to access your endpoints 

By using the @Api\Access(...) annotation above your method, you can restrict the access to your an endpoint. This way you can decide, which Frontend-Users, Frontend-Usergroups, Backend-Users or Backend-Admins are allowed to call your endpoint.

You can restrict access to...

• frontend users (the standard TYPO3 frontend users)
• frontend user groups
• backend users (the endpoint can only be called, if you are logged in to the backend)
• backend admins (you must be logged in to the backend as admin)
• global API-users - defined in the Extension Configuration Manager
• IP-adresses and -ranges
• by using a custom method

Did you know...

You can also restrict the number of requests per minute from a certain IP by using the ApiSecurityMaxRequestsPerMinute()-annotation.

The basic syntax of the @Api\Access-Annotation is:

@Api\Access("options")

Full example

<?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!'];
   }
}

Note that to use the @Api\Access-annotation, you will need to add the use Nng\Nnrestapi\Annotations as Api; line at the top of your script.

Overview of options 

The following permissions exist for @Api\Access(...):

Examples 

/**
 * Open to public. Can be called by anybody.
 *
 * @Api\Access("public")
 * ...
 */

/**
 * This endpoint will be only be accessible by a logged in fe_user.
 *
 * @Api\Access("fe_users")
 * ...
 */

/**
 * Only fe_user with uid 1 can call this endpoint.
 *
 * @Api\Access("fe_users[1]")
 * ...
 */

/**
 * Only fe_user 'david' can call this endpoint!
 *
 * @Api\Access("fe_users[david]")
 * ...
 */

/**
 * Only fe_users 'david' and 'marc' can access this endpoint!
 *
 * @Api\Access("fe_users[david,marc]")
 * ...
 */

/**
 * Only fe_users 'david' and the fe_user with uid '2' can access this endpoint!
 *
 * @Api\Access("fe_users[david,2]")
 * ...
 */

/**
 * Only fe_users 'david' and 'marc' can access this endpoint!
 *
 * @Api\Access({"fe_users[david]", "fe_users[marc]"})
 * ...
 */

/**
 * Only REMOTE_ADDR with IP 90.120.10.* may access this endpoint
 *
 * @Api\Access("ip[90.120.10.*]")
 * ...
 */

@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.*]"})

/**
 * User with IP 90.120.10.* OR any fe_users (with any IP) may access this endpoint
 *
 * @Api\Access("fe_users", "ip_users[90.120.10.*]")
 * ...
 */

Using global configurations 

nnrestapi:
   accessGroups:
      apiUsers: fe_users[3,2]

plugin.tx_nnrestapi.settings {
   accessGroups {
      apiUsers = fe_users[3,2]
   }
}

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

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

/**
 * This endpoint will be only be accessible by a logged in fe_user.
 *
 * @Api\Access("config[apiUsers]")
 * ...
 */

Read on 

How to implement your own method for checking access rights to your endpoint 

In most cases using the @Api\Access(...) annotation will be sufficient to restrict the access to your endpoint to certain frontend-users or user groups.

In case you need to implement your own logic for checking access rights, you can simply define a checkAccess()-method in the class of your endpoint. This will override the default checkAccess()-method from \Nng\Nnrestapi\Api\AbstractApi.

The checkAccess() method must return TRUE, if the user is allowed to access the endpoint. If it returns FALSE, the script will automatically be aborted and the Api will return a HTTP 403 Forbidden header.

Here is an example:

<?php   
namespace My\Extension\Api;

use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */
class Test extends AbstractApi 
{
   /**
    * Completely senseless, but nice demo: 
    * Decide randomly, if the user may access your endpoint.
    *
    * @param array $endpoint information about the endpoint that was supposed to be called
    * @return boolean
    */
   public function checkAccess( $endpoint = [] ) 
   {
      return rand(0, 2) == 1;
   }

   /**
    * This method will only be accessible if the checkAccess-method 
    * above returned true as value.
    * 
    * @return array
    */
   public function getExampleAction()
   {
      return ['result'=>'welcome!'];
   }
}

The above example can be reached with a GET request to:

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

Example: Restricting access to certain IP-adresses 

In this example, we will use the checkAccess() method to check, if the user has a certain IP. The script will only allow access to the methods in this class, if the $remoteAddr matches one of the patterns defined in $allowedIpList:

<?php   
namespace My\Extension\Api;

use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */
class Test extends AbstractApi 
{
   /**
    * Checks, if the IP of the user matches a given adress or pattern.
    *
    * @param array $endpoint
    * @return boolean
    */
   public function checkAccess( $endpoint = [] ) 
   {
      $remoteAddr = $_SERVER['REMOTE_ADDR'];
      $allowedIpList = '109.251.*, 109.252.17.2';
      return \TYPO3\CMS\Core\Utility\GeneralUtility::cmpIP( $remoteAddr, $allowedIpList );
   }

   //... your endpoint-methods come here

}

Example: Check for IP-adresses AND certain fe_user 

If you would like to combine the above example with the check for certain authenticated Frontend-Users like described in @Api\Access(...) you can always call the parent::checkAccess() method in your custom checkAccess() method.

This will process the login in \Nng\Nnrestapi\Api\AbstractApi::checkAccess() that handles restrictions made in the annotations.

<?php   
namespace My\Extension\Api;

use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */
class Test extends AbstractApi 
{
   /**
    * Checks, if the IP of the user matches a given adress or pattern.
    *
    * @param array $endpoint
    * @return boolean
    */
   public function checkAccess( $endpoint = [] ) 
   {
      $remoteAddr = $_SERVER['REMOTE_ADDR'];
      $allowedIpList = '109.251.*, 109.252.17.2';

      // First let's check, if the IP is allowed
      if (!\TYPO3\CMS\Core\Utility\GeneralUtility::cmpIP( $remoteAddr, $allowedIpList )) {
         return false;
      }

      // if yes, then let the AbstractApi take care of checking the fe_users etc.
      return parent::checkAccess( $endpoint );
   }

   //... your endpoint-methods come here
   
}

How to respond with a 403 - Forbidden from inside your method 

If for some reason using the @Api\Access(...) annotation or implementing a custom checkAccess(...)-method are not sufficient, you can always use return $this->response->unauthorized() to abort the further processing inside your endpoint and send a HTTP 403 Forbidden response to the frontend.

Here is an example:

<?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()
   {
      // Only allow access on Fridays
      if (date('w') != 4) {
         return $this->response->unauthorized("Not today, my dear. I've got a headache.");
      }
      return ['result'=>'welcome!'];
   }
}

Logging in as a Frontend-User with the TYPO3 RestApi 

The EXT:nnrestapi ships with an endpoint for logging in as a frontend-user (fe_user) and for checking the login-status of the current user.

nnrestapi offers three different options for authenticating:

• Authorization via JSON Web Tokens (JWT)
• Cookie-based Authorization. This uses the same fe_typo_user cookie that is set for "normal" Frontend-Users.
• Basic Authorization via HTTP

Links and recipes 

To learn how to authenticate, dive in to one of the following recipes:

Full examples on CodePen 

Test your API and play with the code in our CodePens:

| |

How to authenticate a request to your TYPO3 RestApi using HTTP Basic Auth 

Basic access authentication (or "HTTP Basic Auth") is a very simple method for an HTTP user agent (browser) to provide user credentials (username and password) when making a request. In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic <credentials> where "credentials" is the Base64 encoding of ID and password joined by a single colon.

You can define the credentials either...

• on a per-user base by setting an API-key for the frontend user or
• as "global" API-keys that can be used by multiple users and don't depend on a frontend user

Setting HTTP Basic Auth credentials for a single frontend-users 

Follow these steps to set up a username and password for a frontend user that can be used for HTTP basic access authentication.

1. | Create a frontend user In the TYPO3-backend: Create a SysFolder for your frontend users, switch to the list view and add a frontend user to the folder. Depending on your TYPO3 version, you will need to first create a frontend user group.
2. | Set the username In the tab "General" of the new frontend user, enter a Username and Password. The Username will be used for the HTTP Basic Auth. The password you set in the tab "General" is not relevant for the HTTP Basic Auth, it will only be used for the standard TYPO3 login form.
3. | Set the Rest-Api Key Switch to the tab "RestAPI". Enter a password in the field "Rest-Api Key". This will be the password that must be used when sending requests with HTTP Basic Authentication.

4. | Check your @Api\Access()-annotations Make sure, the endpoints that should be accessible by the user have the correct rights set using the @Api\Access() annotation. Examples could be:

   // 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]")

   Copied!

   You can find detailed configuration options in this section of the documentation.

See the examples below on how to create a request in JavaScript using Basic HTTP Authorization.

Setting global HTTP Basic Auth credentials 

Follow these steps, if you would like to create a global API Key that is not bound to a certain TYPO3 frontend user.

1. | Edit extension settings in the backend Switch to the backend module "Settings", then click on the "Configure Extensions" tile.

2. | Set credentials in the extension configuration In the field "API-Keys for BasicAuth" (basic.apiKeys): Enter one user and key per line. In every line, separate the user and key with a colon. The list of users will look like this:

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

   Copied!

3. | Check your @Api\Access()-annotations Make sure, the endpoints that should be accessible by the user have the correct rights set using the @Api\Access() annotation. Examples could be:

   // 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]")

   Copied!
4. | Clear the TYPO3 cache Click the "clear cache" button (red lightning-icon to "clear all caches")

Sending request using HTTP Basic Auth 

Here are some basic examples of how to send requests to your API using HTTP basic authentication:

curl -s -u "fe_username:api_key" https://www.mysite.com/api/endpoint

<?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 );

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 );
});

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) );
});

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 );
      }
   });
   

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

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

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

var xhr = new XMLHttpRequest();
xhr.overrideMimeType('application/json');
xhr.open(method, url);

if (username) {
   xhr.setRequestHeader('Authorization', 'Basic ' + btoa(username + ':' + password));
}

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?');
};

if (['GET', 'DELETE'].indexOf(method) == -1) {
   xhr.send( payload );
} else {
   xhr.send();
}

Full Testscript 

<!doctype html>
<html lang="en">
   <head>
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <title>nnrestapi Demo with HTTP basic 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="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.mywebsite.com/api/endpoint" />
            <label for="url">URL to endpoint</label>
         </div>
         <div class="row">
            <div class="col">
               <div class="form-floating mb-4">
                  <input class="form-control" id="username" value="" />
                  <label for="username">Username</label>
               </div>
            </div>
            <div class="col">
               <div class="form-floating mb-4">
                  <input type="password" class="form-control" id="password" value="" />
                  <label for="password">password</label>
               </div>	
            </div>
         </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>

      document.getElementById('btn-request').addEventListener('click', () => {
         
         const requestUrl = document.getElementById('url-request').value;
         const method = document.getElementById('request-method').value;
         const json = document.getElementById('json-data').value;
         const $result = document.getElementById('result');
         
         const auth = {
            username: document.getElementById('username').value,
            password: document.getElementById('password').value
         };

         axios({
            method: method.toLowerCase(),
            url: requestUrl,
            data: json,
            auth: auth
         }).then( ({data}) => {
            $result.innerText = JSON.stringify( data );
         }).catch( ({response}) => {
            $result.innerText = JSON.stringify( response.data );
         });
         
      });

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

<!doctype html>
<html lang="en">
   <head>
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <title>nnrestapi Demo with HTTP basic 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="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.mywebsite.com/api/endpoint" />
            <label for="url">URL to endpoint</label>
         </div>
         <div class="row">
            <div class="col">
               <div class="form-floating mb-4">
                  <input class="form-control" id="username" value="" />
                  <label for="username">Username</label>
               </div>
            </div>
            <div class="col">
               <div class="form-floating mb-4">
                  <input type="password" class="form-control" id="password" value="" />
                  <label for="password">password</label>
               </div>	
            </div>
         </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://code.jquery.com/jquery-3.6.0.min.js" integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4=" crossorigin="anonymous"></script>
      <script>

         $('#btn-request').click(function () {
            $('#result').show().text('Loading...');

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

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

<!doctype html>
<html lang="en">
   <head>
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <title>nnrestapi Demo with HTTP basic 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="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" />
            <label for="url">URL to endpoint</label>
         </div>
         <div class="row">
            <div class="col">
               <div class="form-floating mb-4">
                  <input class="form-control" id="username" value="" />
                  <label for="username">Username</label>
               </div>
            </div>
            <div class="col">
               <div class="form-floating mb-4">
                  <input type="password" class="form-control" id="password" value="" />
                  <label for="password">password</label>
               </div>	
            </div>
         </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>

         document.getElementById('btn-request').addEventListener('click', () => {

            var requestUrl = document.getElementById('url-request').value;
            var method = document.getElementById('request-method').value;
            var json = document.getElementById('json-data').value;

            var auth = {
               username: document.getElementById('username').value,
               password: document.getElementById('password').value
            };

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

            fetch( requestUrl, 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 );
                     document.getElementById('result').innerText = JSON.stringify( data );
                  }
               });
         });

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

<!doctype html>
<html lang="en">
   <head>
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <title>nnrestapi Demo with HTTP basic 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="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.mywebsite.com/api/endpoint" />
            <label for="url">URL to endpoint</label>
         </div>
         <div class="row">
            <div class="col">
               <div class="form-floating mb-4">
                  <input class="form-control" id="username" value="" />
                  <label for="username">Username</label>
               </div>
            </div>
            <div class="col">
               <div class="form-floating mb-4">
                  <input type="password" class="form-control" id="password" value="" />
                  <label for="password">Password</label>
               </div>	
            </div>
         </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 for older
          * browsers not supporting fetch()
          * 
          */
         function sendRequest( url, payload, method, auth, done, fail ) {

            if (typeof payload == 'object') {
               payload = JSON.stringify(payload);
            }

            var xhr = new XMLHttpRequest();
            xhr.overrideMimeType('application/json');
            xhr.open(method, url);

            if (auth.username) {
               xhr.setRequestHeader('Authorization', 'Basic ' + btoa(auth.username + ':' + auth.password));
            }

            xhr.onload = function () {
               var data = JSON.parse( xhr.responseText );
               if (xhr.status != 200) {
                  if (fail) fail( data );
                  return false;
               }
               if (done) done( data );
            };

            xhr.onerror = function () {
               fail({
                  status: 0,
                  error: 'Some other error... probably wrong url?'
               });
            };

            if (['GET', 'DELETE'].indexOf(method) == -1) {
               xhr.send( payload );
            } else {				
               xhr.send();
            }
         }


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

            var requestUrl = document.getElementById('url-request').value;
            var method = document.getElementById('request-method').value;
            var json = document.getElementById('json-data').value;

            var auth = {
               username: document.getElementById('username').value,
               password: document.getElementById('password').value
            };

            sendRequest( requestUrl, json, method, auth, requestSuccessful, requestFailed  );

            function requestSuccessful( data ) {
               document.getElementById('result').innerText = JSON.stringify( data );
            }

            function requestFailed( data ) {
               alert( 'Error ' + data.status + ': ' + data.error );   
            }

         });

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