Implementing READ operation
Table of contents
- What you need
- 1. Map HTTP method
- 2. Handle parameters
- 3. Implement service code
- 4. Return response
- 5. Test retrieving a blog post
- Next step
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.
- Main.java from Step 1. Create a server
- BlogPost.java from Step 2. Prepare a data object
- BlogService.java from Step 3. Add services to a server
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:
Declare a service method
getBlogPost()
in the classBlogService
.Map this service method with the HTTP GET method by adding the
@Get
annotation as follows.Bind the endpoint
/blogs
to the method.BlogService.javaimport 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:
- To take in a path parameter, add
/:id
to the@Get
annotation's parameter as in line 6. - Inject the path parameter to the service method, annotate the parameter with
@Param
as in line 7.
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.
@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:
- Replace the return type of the
getBlogPost()
method fromvoid
toHttpResponse
. - Return a response using Armeria's
HttpResponse
containing the content of the blog post retrieved.
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.
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.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":...}
Try retrieving blog posts we just created:
Single postMultiple postsLet'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.