REST tutorial introduction

Using Armeria's annotations, you can build RESTful services on the go. Through this tutorial, you'll learn to build a RESTful service with Armeria. In particular, you'll be using these Armeria features:

• Service annotations
• Request converter
• Parameter injection
• Exception handler
• Blocking task executor

This tutorial is based on a sample service, a minimal blog service, with which you can create, read, update, and delete blog posts.

Follow this tutorial to write a service yourself or try running the sample service right away.

Assumptions

This tutorial assumes that you have:

• Experience in building services in Java
• Experience in Java frameworks for server-side programming
• Understanding of RESTful APIs and how to implement them

Prerequisites

To run and develop the sample service, set your computer with the requirements:

• JDK 11 or higher
• Gradle: Set your Gradle to compile Java with the -parameters option

Sample service

The sample service provides you implementations of CRUD operations as specified below.

Operation	Method	Annotation
Create	createBlogPost()	@Post
Read	getBlogPost(), getBlogPosts()	@Get
Update	updateBlogPost()	@Put
Delete	deleteBlogPost()	@Delete

The sample service code consists of the following folders and files.

rest-api-annotated-service/
├─ src/
│  ├─ main/
│  │  ├─ java/
│  │  │  ├─ example.armeria.server.blog/
│  │  │  │  ├─ BadRequestExceptionHandler.java
│  │  │  │  ├─ BlogPost.java
│  │  │  │  ├─ BlogPostRequestConverter.java
│  │  │  │  ├─ BlogService.java
│  │  │  │  └─ Main.java
│  └─ test/
│     └─ java/
│        └─ example.armeria.server.blog/
│           └─ BlogServiceTest.java
└─ build.gradle

tip

To keep our focus on Armeria, this tutorial and the sample service implement memory-based operations instead of using a database.

Build and run sample service

Have a go at running the sample service and experience the outcome of this tutorial. Using Armeria's Documentation Service, you can see a server running, receiving requests and sending responses.

1. Download the code from here.
2. Build the sample service using the Gradle Wrapper.

$ ./gradlew build

3. Run the sample service again, using the Gradle Wrapper.

$ ./gradlew run

4. Open the Documentation service page on your web browser at http://127.0.0.1:8080/docs.

Try writing blog service yourself

Use the sample service's build.gradle file to start building the service from scratch. Below is a part of the build.gradle file for the sample service.

apply plugin: 'java'
apply plugin: 'idea'
apply plugin: 'eclipse'

repositories {
  mavenCentral()
}

dependencies {
  implementation "com.linecorp.armeria:armeria:1.34.1"

  // Logging
  runtimeOnly 'ch.qos.logback:logback-classic:1.5.21'

  runtimeOnly 'org.slf4j:log4j-over-slf4j:1.7.36'

  testImplementation "org.junit.jupiter:junit-jupiter:5.14.1"

  testImplementation "com.linecorp.armeria:armeria-junit5:1.34.1"

  testImplementation "org.assertj:assertj-core:3.27.6"
}

Start writing the blog service yourself by following the tutorial step by step:

1. Creating a server
2. Preparing a data object
3. Adding services to server
4. Implementing CREATE operation
5. Implementing READ operation
6. Implementing UPDATE operation
7. Implementing DELETE operation