Service Definition

From messages to an API

The Protocol Buffers module gave you the nouns — messages, the shape of your data. This module gives you the verbs: a service is a named group of methods (rpcs), and each method is one request message in, one response message out.

That single decision — methods, not resources — is what makes the client feel like a local function call. Here everything comes together into an actual API surface.

What this module covers

Lesson	What you’ll learn
Defining Services	`service` and `rpc` syntax, package naming, and API versioning in the package path
The Four RPC Types	Unary, server-streaming, client-streaming, bidirectional — and the message flow of each
Designing Methods	Wrapper request/response messages, naming, pagination, and idempotency
Errors & Status Codes	The status code model and rich errors with `google.rpc.Status`

A service is a contract for behavior

flowchart LR
  subgraph svc["service UserService"]
    m1["rpc GetUser(GetUserRequest) → User"]
    m2["rpc CreateUser(CreateUserRequest) → User"]
    m3["rpc ListUsers(ListUsersRequest) → ListUsersResponse"]
  end
  client["client stub"] -->|calls| svc
  svc -->|typed response| client

A service groups methods; each method maps a request to a response

By the end of this module you’ll be able to read any .proto service block and know exactly what calls it offers, which of them stream, and how it reports failure.