REST tutorial introduction

• Assumptions

• Prerequisites

• Sample service

  • Sample service structure
  • build.gradle

• 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:

• 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. 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.

Sample service structure

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

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.

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

repositories {
    mavenCentral()
}

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

    // Logging
    runtimeOnly 'ch.qos.logback:logback-classic:1.2.11'
    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