gRPC tutorial introduction

Learn to build a gRPC service with Armeria by writing a blog service in gRPC. This tutorial is based on a sample service, a minimal blog service, with which you can create, read, update, and delete blog posts.

Before we get our hands on the tutorial, let's switfly go over Armeria's gRPC features. Armeria supports features that the upstream (gRPC-Java) does not support.

  • Protocol
    • HTTP/1.1
    • HTTP/2 (upstream)
  • Serialization format - Framed
    • gRPC protobuf: application/grpc+proto (upstream)
    • gRPC JSON: application/grpc+json
    • gRPC Web: application/grpc-web+proto
    • gRPC Web JSON: application/grpc-web+json
    • gRPC Web Text: application/grpc-web-text+proto
  • Serialization format - Unframed
    • Protobuf: application/protobuf
    • JSON: application/json
  • HTTP level decorator
  • Richer error handling
  • HTTP-to-JSON transcoding
  • Customizing service method paths
  • gRPC documentation service
  • gRPC status monitoring with MetricCollectingService

To keep our focus on Armeria, this tutorial and the sample service implement memory-based operations instead of using database. 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 gRPC and experience in implementing gRPC services

Prerequisites

To run and develop the sample service, you need JDK 11 or higher.

Build and run sample service

The sample service provides you implementations of CRUD operations with corresponding service methods. Have a go at running the sample gRPC service and see the outcome of this tutorial. Using Armeria's Documentation Service, you can easily verify a server is 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

Have a go at writing the blog service yourself, starting with defining the service. Use the sample service's build.gradle to start building the service from scratch.

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

repositories {
  mavenCentral()
}

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

  implementation "com.linecorp.armeria:armeria-grpc:1.27.3"

  // Logging
  runtimeOnly "ch.qos.logback:logback-classic:1.4.14"
}