REST tutorial introduction

Assumptions
Prerequisites
Sample service
Build and run sample service
Try writing blog service yourself

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:

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

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.

Download the code from here.
Build the sample service using the Gradle Wrapper.
```
$ ./gradlew build
```
Run the sample service again, using the Gradle Wrapper.
```
$ ./gradlew run
```
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.

build.gradle

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

repositories {
  mavenCentral()
}

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

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

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

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

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

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