Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: less detail in Hello World #7

Merged
merged 1 commit into from
Nov 20, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ make managed

2. Create the full site
```bash
make local
make local open
```

This command will execute a Docker-based build process that compiles the documentation. The generated documentation will be output to the `target/site` directory.
Expand Down
17 changes: 10 additions & 7 deletions docs/src/modules/ROOT/pages/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -53,12 +53,15 @@ Akka's event-sourced model is fundamentally streaming-based, providing a robust
== Getting Started with Akka
There are multiple ways to get started with Akka.

* *Deploy, scale, and replicate a service.* Take the 5 minute walk-through by creating a free account at https://console.akka.io/register[akka.io].
* *Learn* the Akka xref:concepts:architecture-model.adoc[] for architects and developers.
* *Learn* the Akka xref:concepts:deployment-model.adoc[] for operators.
* *Learn* the Akka xref:concepts:development-process.adoc[]
* *Start a local development environment* Getting started with Integrated Development Environment (IDE) integration, local debugging, and packing services into images. xref:java:running-locally.adoc[]
* *Learn how to implement a "Hello World" service.* xref:java:author-your-first-service.adoc[]
* *Review a pre-built service implementation.* See some Akka components in the xref:java:shopping-cart-quickstart.adoc[]
* Hands-on
** *Deploy, scale, and replicate a pre-built service.* Take the 5 minute walk-through by creating a free account at https://console.akka.io/register[akka.io].
** *Implement a "Hello World" service.* xref:java:author-your-first-service.adoc[].
** *Review a pre-built service implementation.* See some Akka components in the xref:java:shopping-cart-quickstart.adoc[].

* Understand
** ... the Akka xref:concepts:architecture-model.adoc[] for architects and developers.
** ... the Akka xref:concepts:deployment-model.adoc[] for operators.
** ... the Akka xref:concepts:development-process.adoc[].
* *Start a local development environment* Getting started with Integrated Development Environment (IDE) integration, local debugging, and packing services into images. See xref:java:running-locally.adoc[].
* *Setup* CI/CD pipelines, external Docker repositories, external messaging brokers, or 3rd party observability.
See xref:operations:index.adoc[Operating Services] for more information.
32 changes: 6 additions & 26 deletions docs/src/modules/java/pages/author-your-first-service.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ NOTE: If you'd rather skip past this and want to review an already completed app

== Prerequisites

include::ROOT:partial$cloud-dev-prerequisites.adoc[]
include::ROOT:partial$local-dev-prerequisites.adoc[]


== Generate and build the skeleton project
Expand Down Expand Up @@ -152,27 +152,18 @@ curl localhost:9000/hello/hello/Bob/30

=== Request body ===

To accept an HTTP JSON body, specify a parameter that is a class that https://github.com/FasterXML/jackson?tab=readme-ov-file#what-is-jackson[Jackson] can deserialize:
To accept an HTTP JSON body, specify a parameter that is a Java record.

[source,java]
.HelloWorldEndpoint.java
----
include::example$doc-snippets/src/main/java/com/example/api/ExampleEndpoint.java[tag=request-body]
----
<1> A class that Jackson can serialize and deserialize to JSON
<1> The record will serialized and deserialized as JSON
<2> A parameter of the request body type
<3> When combining request body with path variables
<4> The body must come last in the parameter list

Additionally, the request body parameter can be of the following types:

* `String` for any request with a text content type, the body decoded into a string
* `java.util.List<T>` where `T` is a type Jackson can deserialize, accepts a JSON array.
* `akka.http.javadsl.model.HttpEntity.Strict` for the entire request body as bytes together with the content type for
arbitrary payload handling.
* `akka.http.javadsl.model.HttpRequest` for a low level, streaming representation of the entire request
including headers. See xref:http-endpoints.adoc#_low_level_requests[] below for more details

You can now call these commands as well
[source, command line]
----
Expand All @@ -182,30 +173,19 @@ curl -i -XPOST -H "Content-Type: application/json" localhost:9000/hello/hello -d

=== Response body ===

To return response with JSON, the return value can be a class that Jackson can serialize:
To return response with JSON, the return value can be a record that gets serialized as JSON:

[source,java]
.HelloWorldEndpoint.java
----
include::example$doc-snippets/src/main/java/com/example/api/ExampleEndpoint.java[tag=response-body]
----
<1> Returning an object that Jackson can serialize into JSON

In addition to an object that can be turned to JSON, a request handler can return the following:

* `null` or `void` to return an empty body.
* `String` to return a UTF-8 encoded `text/plain` HTTP response.
* `CompletionStage<T>` to respond based on an asynchronous result.
** When the completion stage is completed with a `T` it is
turned into a response.
** If it is instead failed, the failure leads to an error response according to
the error handling explained in xref:http-endpoints.adoc#_error_responses[error responses].
* `akka.http.javadsl.model.HttpResponse` for complete control over the response, see xref:http-endpoints.adoc#_low_level_responses[] below
<1> Returning a record that gets serialized as JSON

[source, command line]
----
curl localhost:9000/hello/hello/Bob/30
----

== Next steps
Now that you have a basic service running, it's time to learn more about building real services in Akka. See the xref:java:shopping-cart-quickstart.adoc[] to build a more realistic application.
Now that you have a basic service running, it's time to learn more about building real services in Akka. See the xref:java:shopping-cart-quickstart.adoc[] to build a more realistic application and learn how to deploy it to https://console.akka.io[akka.io].
Loading