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:

This tutorial is based on a sample service, a minimal blog service, with which you can create, read, update, and delete blog posts. To keep our focus on Armeria, this tutorial and the sample service use memory-based operations instead of database operations.

Try writing a service yourself by following this tutorial or have a go at 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.

OperationMethodAnnotation
CreatecreateBlogPost()@Post
ReadgetBlogPost(), getBlogPosts()@Get
UpdateupdateBlogPost()@Put
DeletedeleteBlogPost()@Delete

Sample service structure

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

plantuml

build.gradle

Here is a part of the build.gradle file for the sample service. If you are trying the tutorial from scratch, base your file on the sample service's.

build.gradle
apply plugin: 'java'
apply plugin: 'idea'
apply plugin: 'eclipse'

repositories {
    mavenCentral()
}

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

    // Logging
    runtimeOnly 'ch.qos.logback:logback-classic:1.4.14'
    runtimeOnly 'org.slf4j:log4j-over-slf4j:1.7.36'
}

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

Try writing the blog service yourself by following the guides in the given order:

  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