> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to create a custom REST service in an Atoti Server Extension

<Note>
  You can find all the necessary information on Spring REST services in the [Spring documentation](https://spring.io/guides/tutorials/rest).
</Note>

<Info>
  ### Prerequisites

  This guide assumes you have already created a Maven project with `atoti-server-extension-parent` as described in the [Atoti Server Extension reference](../atoti_server_extension#configuration).
</Info>

In this guide, we show the steps required to create a custom REST service in an Atoti Server Extension.

## 1. Create a custom REST service

Since Atoti Server Extension is a Spring Boot application, you can create a custom REST service by creating a Spring `@RestController` class.

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
/** A REST controller that exposes cube information. */
@RestController
@RequestMapping("/app-extension")
@RequiredArgsConstructor
public class AtotiServerExtensionRestController {
  /** These Beans are available with the atoti-server-runtime-extension module. */
  private final IActivePivotManager activePivotManager;
  private final IDatastore datastore;
  @GetMapping("/cubes")
  public ResponseEntity<String> getCubes() {
    final String cubes = String.join(",", activePivotManager.getActivePivots().keySet());
    return ResponseEntity.of(Optional.of(cubes));
  }
}
```

## 2. Secure the REST service

<Warning>
  ### Important

  All custom REST endpoints **must** have a security configuration, even if you want to allow unauthenticated access.
  Without security configuration, your endpoints will not be accessible and will return a 403 Forbidden error.
</Warning>

You need to create a security configuration that defines which users can access your custom endpoints.
This is done by creating a `SecurityFilterChain` bean, you can find more information on Atoti endpoint security [here](./configure-rest-endpoint-security).

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
@EnableWebSecurity
@Configuration
public class SecurityConfig {
  /** Configures the security for the custom REST service. */
  @Bean
  @Order(20)
  @Lazy(false)
  public SecurityFilterChain customRestServiceSecurity(
      final HttpSecurity http, final MachineToMachineSecurityDsl dsl) throws Exception {
    http.with(dsl, d -> d.setScope(Set.of(MachineToMachineSecurityDsl.Scope.SECURITY)));
    http.securityMatcher("/app-extension/**")
        .authorizeHttpRequests(
            request -> request.requestMatchers("/app-extension/cubes").hasRole("ADMIN"));
    return http.build();
  }
```

Key points about the security configuration:

* The `@Order` annotation determines when this security filter chain is evaluated. Lower values have higher priority. Use a value between the standard Atoti filter chains (e.g., 20).
* The `@Lazy(false)` annotation ensures the security configuration is loaded at application startup.
* Use `http.securityMatcher("/your-path/**")` to specify which endpoints this configuration applies to.
* Use `http.authorizeHttpRequests()` to define authorization rules:
  * `.hasRole("ADMIN")` - requires the user to have the ADMIN role
  * `.permitAll()` - allows unauthenticated access
  * `.authenticated()` - requires any authenticated user
* The `MachineToMachineSecurityDsl.Scope.SECURITY` scope applies authentication and authorization filters.

## 3. Register the REST service and security configuration

To register your custom REST service and its security configuration, you need to import both in your `@AutoConfiguration` class [see](../atoti_server_extension#creating-the-autoconfiguration-class).

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
/* Autoconfiguration for the Atoti Server Extension. */
@AutoConfiguration
@Import({AtotiServerExtensionRestController.class, SecurityConfig.class})
public class AtotiServerExtensionAutoConfiguration {}
```