Designing HTTP Endpoints

  @Get("/hello/{name}") (1)
  public String hello(String name) { (2)
    return "Hello " + name;
  }

  @Get("/hello/{name}/{age}") (3)
  public String hello(String name, int age) { (4)
    return "Hello " + name + "! You are " + age + " years old";
  }

  public record GreetingRequest(String name, int age) {} (1)

  @Post("/hello")
  public String hello(GreetingRequest greetingRequest) { (2)
    return "Hello " + greetingRequest.name + "! " +
        "You are " + greetingRequest.age + " years old";
  }

  @Post("/hello/{number}") (3)
  public String hello(int number, GreetingRequest greetingRequest) { (4)
    return number + " Hello " + greetingRequest.name + "! " +
        "You are " + greetingRequest.age + " years old";
  }

  public record MyResponse(String name, int age) {}

  @Get("/hello-response/{name}/{age}")
  public MyResponse helloJson(String name, int age) {
    return new MyResponse(name, age); (1)
  }

  @Get("/hello-code/{name}/{age}")
  public String helloWithValidation(String name, int age) {
    if (age > 130)
      throw HttpException.badRequest("It is unlikely that you are " + age + " years old");  (1)
    else
      return " Hello " + name + "!";  (2)
  }

  record HelloResponse(String greeting) {}

  @Get("/hello-low-level-response/{name}/{age}")
  public HttpResponse lowLevelResponseHello(String name, int age) { (1)
    if (age > 130)
      return HttpResponses.badRequest("It is unlikely that you are " + age + " years old");  (2)
    else
      return HttpResponses.ok(new HelloResponse("Hello " + name + "!"));  (3)
  }

  record HelloResponse(String greeting) {}

  @Get("/hello-low-level-response/{name}/{age}")
  public HttpResponse lowLevelResponseHello(String name, int age) { (1)
    if (age > 130)
      return HttpResponses.badRequest("It is unlikely that you are " + age + " years old");  (2)
    else
      return HttpResponses.ok(new HelloResponse("Hello " + name + "!"));  (3)
  }

  @Get("/hello-lower-level-response/{name}/{age}")
  public HttpResponse lowerLevelResponseHello(String name, int age) {
    if (age > 130)
      return HttpResponse.create()
          .withStatus(StatusCodes.BAD_REQUEST)
          .withEntity("It is unlikely that you are " + age + " years old");
    else {
        var jsonBytes = JsonSupport.encodeToAkkaByteString(new HelloResponse("Hello " + name + "!")); (1)
        return HttpResponse.create() (2)
            .withEntity(ContentTypes.APPLICATION_JSON, jsonBytes); (3)
    }
  }

  private final static ContentType IMAGE_JPEG = ContentTypes.create(MediaTypes.IMAGE_JPEG);
  @Post("/post-image/{name}")
  public String lowLevelRequestHello(String name, HttpEntity.Strict strictRequestBody) {
    if (!strictRequestBody.getContentType().equals(IMAGE_JPEG)) (1)
      throw HttpException.badRequest("This service only accepts " + IMAGE_JPEG);
    else {
      return "Got " + strictRequestBody.getData().size() + " bytes for image name " + name;  (2)
    }
  }

public class ExampleEndpoint extends AbstractHttpEndpoint {

  private final Materializer materializer;

  public ExampleEndpoint(Materializer materializer) { (1)
    this.materializer = materializer;
  }

  @Get("/hello-request-header/{name}")
  public CompletionStage<String> lowerLevelRequestHello(String name, HttpRequest request) {
    if (request.getHeader("X-my-special-header").isEmpty()) {
      return request.discardEntityBytes(materializer).completionStage().thenApply(__ -> { (2)
        throw HttpException.forbidden("Missing the special header");
      });
    } else {
      return request.entity().toStrict(1000, materializer).thenApply(strictRequestBody ->  (3)
        " Hello " + name + "! " +
            "We got your " + strictRequestBody.getData().size() + " bytes " +
            "of type " + strictRequestBody.getContentType()
      );
    }
  }

  @Get("/hello-request-header-from-context")
  public String requestHeaderFromContext() {
    var name = requestContext().requestHeader("X-my-special-header") (1)
        .map(HttpHeader::value)
        .orElseThrow(() -> new IllegalArgumentException("Request is missing my special header"));

    return "Hello " + name + "!";
  }

  @Get("/") (1)
  public HttpResponse index() {
    return HttpResponses.staticResource("index.html"); (2)
  }

  @Get("/favicon.ico") (3)
  public HttpResponse favicon() {
    return HttpResponses.staticResource("favicon.ico"); (4)

  }

  @Get("/static/**") (1)
  public HttpResponse webPageResources(HttpRequest request) { (2)
    return HttpResponses.staticResource(request, "/static/"); (3)
  }

  @Get("/current-time")
  public HttpResponse streamCurrentTime() {
    Source<Long, Cancellable> timeSource =
        Source.tick(Duration.ZERO, Duration.ofSeconds(5), "tick") (1)
            .map(__ -> System.currentTimeMillis()); (2)

    return HttpResponses.serverSentEvents(timeSource); (3)
  }

  @Get("/by-name-sse/{name}")
  public HttpResponse continousByNameServerSentEvents(String name) {
    // view will keep stream going, toggled with streamUpdates = true on the query
    Source<CustomersByName.CustomerSummary, NotUsed> customerSummarySource = componentClient.forView() (1)
        .stream(CustomersByName::continuousGetCustomerSummaryStream)
        .source(name);

    return HttpResponses.serverSentEvents(customerSummarySource); (2)
  }

  private record CustomerStreamState(Optional<Customer> customer, boolean isSame) {}

  @Get("/stream-customer-changes/{customerId}")
  public HttpResponse streamCustomerChanges(String customerId) {
    Source<Customer, Cancellable> stateEvery5Seconds =
        // stream of ticks, one immediately, then one every five seconds
        Source.tick(Duration.ZERO, Duration.ofSeconds(5), "tick") (1)
          // for each tick, request the entity state
          .mapAsync(1, __ ->
            componentClient.forKeyValueEntity(customerId)
                .method(CustomerEntity::getCustomer)
                .invokeAsync().handle((Customer customer, Throwable error) -> {
                  if (error == null) {
                    return Optional.of(customer);
                  } else if (error instanceof IllegalArgumentException) {
                    // calling getCustomer throws IllegalArgument if the customer does not exist
                    // we want the stream to continue polling in that case, so turn it into an empty optional
                    return Optional.<Customer>empty();
                  } else {
                    throw new RuntimeException("Unexpected error polling customer state", error);
                  }
                })
          )
          // then filter out the empty optionals and return the actual customer states for nonempty
          // so that the stream contains only Customer elements
          .filter(Optional::isPresent).map(Optional::get);

    // deduplicate, so that we don't emit if the state did not change from last time
    Source<Customer, Cancellable> streamOfChanges = (2)
        stateEvery5Seconds.scan(new CustomerStreamState(Optional.empty(), true),
          (state, newCustomer) ->
            new CustomerStreamState(Optional.of(newCustomer), state.customer.isPresent() && state.customer.get().equals(newCustomer))
        ).filterNot(state -> state.isSame || state.customer.isEmpty())
        .map(state -> state.customer.get());

    // now turn each changed internal state representation into public API representation,
    // just like get endpoint above
    Source<ApiCustomer, Cancellable> streamOfChangesAsApiType = (3)
        streamOfChanges.map(customer -> toApiCustomer(customerId, customer));

    // turn into server sent event response
    return HttpResponses.serverSentEvents(streamOfChangesAsApiType); (4)
  }