
# Endpoints of your own

An `@Endpoint` class adds an endpoint next to `health` and `info`, under `/actuator/<id>`, with the same rules for enabling, exposure, security and media types. It is Spring Boot's `@Endpoint`.

## Why

Operations data that belongs to the application (feature flags, queue sizes, a cache's statistics) fits the actuator: one base path, one security rule, one JSON style. Writing it as an endpoint instead of a controller gives it all of that for free.

## Example

```dart
// GET /actuator/features and GET /actuator/features/{name}
@Endpoint(id: 'features')
class FeaturesEndpoint {
  FeaturesEndpoint(this.flags);

  final FeatureFlags flags;

  @ReadOperation()
  Map<String, bool> features() => flags.all;

  @ReadOperation()
  bool? feature(@Selector() String name) => flags.all[name]; // null answers 404
}
```

```properties
management.endpoints.web.exposure.include=health,features
```

```console
$ curl localhost:8080/actuator/features
{"search":true,"recommendations":false}
$ curl localhost:8080/actuator/features/search
true
```

## @Endpoint

| Parameter | Default | Meaning |
|---|---|---|
| `id` | required | The endpoint's id: its path under the base path, and the `<id>` of its properties |
| `enableByDefault` | `true` | Whether it is enabled when no property says otherwise |
| `name` | from the class | The bean name |

`@Endpoint` is a `@Component`: the class must be in the scanned code. The endpoint is found in the bean definitions the generator writes, without reflection.

It follows the same rules as the built-in ones: `management.endpoint.features.enabled` or `.access`, `management.endpoints.web.exposure.include`, `management.endpoints.web.path-mapping.features`. See [Endpoints](endpoints.md).

## Operations

| Element | Becomes |
|---|---|
| `@ReadOperation()` method | A `GET` (and `HEAD`) operation. `produces:` lists its media types |
| `@Selector()` parameter | A path segment, in order: `/actuator/features/{name}` |
| `@Selector(match: SelectorMatch.allRemaining)` parameter | The rest of the path, as a `List<String>` |
| another parameter | A query parameter, converted to its type; missing (when not nullable) or unconvertible is a `400` |
| a `SecurityContext` parameter | The request's user and roles |
| a `null` result | `404` |
| a `WebEndpointResponse(body:, status:, contentType:)` result | That status and media type |
| a `Future` result | Awaited |

The result is written as JSON. Only read operations exist so far: there is no `@WriteOperation` or `@DeleteOperation`.

## @EndpointWebExtension

A web extension replaces operations of an endpoint over HTTP, for example to answer another status, as the health endpoint's extension does:

```dart
@EndpointWebExtension(endpoint: FeaturesEndpoint)
class FeaturesWebExtension {
  FeaturesWebExtension(this.delegate);

  final FeaturesEndpoint delegate;

  @ReadOperation()
  WebEndpointResponse<bool> feature(@Selector() String name) {
    final value = delegate.feature(name);
    return value == null
        ? const WebEndpointResponse(status: 404)
        : WebEndpointResponse(body: value);
  }
}
```

## In Spring (Java)

```java
@Endpoint(id = "features")
@Component
class FeaturesEndpoint {
  @ReadOperation
  Map<String, Boolean> features() { ... }

  @ReadOperation
  Boolean feature(@Selector String name) { ... }
}
```

The same annotations. Differences: read operations only, no JMX, and the endpoint is found at build time.

## See also

- [Endpoints](endpoints.md)
- [Security](security.md)
- [Health](health.md)
