Implementing READ operation

In this step, we'll implement two methods at once. One is for retrieving a single post and another for multiple blog posts. By completing this step, you'll learn to map your service with the HTTP GET (@Get) method, use parameter injection (@Param), set default parameter value (@Default), and return a JSON object (@ProducesJson) as a response.

What you need

You must have the following files ready for retrieving a blog post. You can always download the full version, instead of creating one yourself.

1. Map HTTP method

Let's start mapping the HTTP GET method with our service method:

Map the HTTP GET method for retrieving a single post:

  1. Declare a service method getBlogPost() in the class BlogService.

  2. Map this service method with the HTTP GET method by adding the @Get annotation as follows.

  3. Bind the endpoint /blogs to the method.

    BlogService.java
    import com.linecorp.armeria.server.annotation.Get;
    
    public final class BlogService {
      ...
    
      @Get("/blogs")
      public void getBlogPost(int id) {
        // Retrieve a single post
      }
    }

2. Handle parameters

Take in information through path and query parameters for retrieving blog posts. For retrieving a single post, we'll take a blog post ID as the path parameter. For multiple posts, we'll take the sorting order as a query parameter.

Let's handle parameters for retrieving a single post:

  1. To take in a path parameter, add /:id to the @Get annotation's parameter as in line 6.
  2. Inject the path parameter to the service method, annotate the parameter with @Param as in line 7.
BlogService.java
1import com.linecorp.armeria.server.annotation.Param;
2
3public final class BlogService {
4 ...
5
6 @Get("/blogs/:id")
7 public void getBlogPost(@Param int id) {
8   // Retrieve a single post
9 }
10}

3. Implement service code

In this step, write the code required for service itself.

To retrieve a single blog post information, copy the following code inside the getBlogPost() method.

BlogService.java
@Get("/blogs")
public void getBlogPost(@Param int id) {
  BlogPost blogPost = blogPosts.get(id);
}

4. Return response

Let's return a response for the service call.

To return a response for getting a single post:

  1. Replace the return type of the getBlogPost() method from void to HttpResponse.
  2. Return a response using Armeria's HttpResponse containing the content of the blog post retrieved.
BlogService.java
import com.linecorp.armeria.common.HttpResponse;

public final class BlogService {
  @Get("/blogs/:id")
  public HttpResponse getBlogPost(@Param int id) {
    ...

    return HttpResponse.ofJson(blogPost);
  }
}

5. Test retrieving a blog post

Let's test retrieving a single and multiple posts.

  1. Run the server like we did in Step 1. Create a server by running the main() method or using Gradle. When you see the message, "Server has been started", you can try testing service methods.

  2. Create a couple of blog posts to test retrieving a blog post and get the ID value returned. Enter the cURL commands below.

    $ curl --request POST 'localhost:8080/blogs' \
    -H 'Content-Type: application/json' \
    -d '{"title":"First post for testing", "content":"Test reading."}'
    $ curl --request POST 'localhost:8080/blogs' \
    -H 'Content-Type: application/json' \
    -d '{"title":"Second post for testing", "content":"Test reading a post."}'

    For each command, you'll get a response similar to the following.

    {"id":0,"title":"First post for testing","content":"Test reading.","createdAt":...,"modifiedAt":...}
    
    {"id":1,"title":"Second post for testing","content":"Test reading a post.","createdAt":...,"modifiedAt":...}
  3. Try retrieving blog posts we just created:

    Let's try retrieving the second blog post we created. Pass the path parameter (blog ID) as 1.

    $ curl --request GET 'localhost:8080/blogs/1'

    You'll get a return value similar to this:

    {
      "id":1,
      "title":"Second post for testing",
      "content":"Test reading a post.",
      "createdAt":...,
      "modifiedAt":...
    }

You can test this also with Armeria's Documentation service. See Using DocService after adding service methods for instructions.

Next step

In this step, we've implemented methods for a READ operation and used Armeria's annotations; @Get, @ProducesJson, @Param, and @Default.

Next, at Step 6. Implement UPDATE, we'll implement an UPDATE operation to modify existing blog posts.