Package akka.javasdk.annotations.http

Annotation Interface HttpEndpoint

@Target(TYPE)
@Retention(RUNTIME)
@Documented
public @interface HttpEndpoint

Annotation to mark a class as an HTTP endpoint that exposes RESTful APIs.

HTTP endpoints handle incoming HTTP requests and can return responses in various formats including JSON, plain text, or custom content types. They provide the external API for your service.

Basic Structure: The annotated class should be public with a public constructor. Methods annotated with HTTP verb annotations (Get, Post, Put, Patch, Delete) handle requests.

Path Configuration: The annotation value specifies a common path prefix for all methods in the class. Individual method paths are combined with this prefix to form the complete endpoint URL.

Method Features:

• Path Parameters: Use {paramName} in paths to extract URL segments
• Request Bodies: Accept JSON by adding parameters Jackson can deserialize
• Query Parameters: Access via RequestContext.queryParams()
• Headers: Access via RequestContext.requestHeader()

Response Types:

• String - text/plain responses
• Objects - JSON responses (serialized with Jackson)
• HttpResponse - full control over response
• CompletionStage<T> - asynchronous responses

Constructor Injection: Annotated classes can accept the following types in their constructor:

• ComponentClient - for calling other components
• HttpClientProvider - for HTTP service calls
• RequestContext - for request context access
• TimerScheduler
• Materializer
• Config
• Span
• Custom types provided by a DependencyProvider

Request Context Access: If the annotated class extends AbstractHttpEndpoint, the request context is available via requestContext() without constructor injection.

Security: Always annotate endpoints with appropriate Acl annotations to control access. Without ACL annotations, no clients are allowed to access the endpoint.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	value

Element Details

value

String value

Default:

""