user_service.proto

proto3 · package acme.user.v1
1syntax = "proto3";
2 
3package acme.user.v1;
4 
5import "acme/user/v1/user.proto";
6import "google/api/annotations.proto";
7 
8option go_package = "acme.example/user/v1;userv1";
9 
10// Manages user accounts for the Acme identity platform.
11//
12// ## Operations at a glance
13//
14// | RPC | HTTP binding | Use |
15// | --- | --- | --- |
16// | `GetUser` | `GET /v1/users/{id}` | Read one account. |
17// | `ListUsers` | `GET /v1/users` | Read a page of accounts. |
18// | `CreateUser` | `POST /v1/users` | Submit a new account. |
19// | `WatchUsers` | No HTTP binding | Stream account changes over gRPC. |
20//
21// ## Exploring the API
22//
23// 1. Start with the [User message](../../messages/acme.user.v1.User/) for the
24//    account shape and a JSON example.
25// 2. Inspect each RPC's request and response types.
26// 3. Follow **View source** to see the HTTP and idempotency options in context.
27//
28// > These bindings describe an example API. The documentation site does not
29// > host a running user service.
30service UserService {
31  // Fetch a user by id.
32  //
33  // ## HTTP example
34  //
35  // For a deployment at `https://api.example.com`, the binding maps to:
36  //
37  // ```sh
38  // curl --request GET \
39  //   'https://api.example.com/v1/users/550e8400-e29b-41d4-a716-446655440000'
40  // ```
41  //
42  // The request `id` must be a UUID. The response wraps the account in `user`.
43  // This method is marked `NO_SIDE_EFFECTS`.
44  rpc GetUser(GetUserRequest) returns (GetUserResponse) {
45    option (google.api.http) = {
46      get: "/v1/users/{id}"
47    };
48    option idempotency_level = NO_SIDE_EFFECTS;
49  }
50 
51  // List users with optional server-side filtering.
52  //
53  // ### Pagination
54  //
55  // - `page_size` accepts values from `0` through `100`.
56  // - Pass a returned `next_page_token` as `page_token` to request another page.
57  // - Treat page tokens as **opaque strings** rather than parsing their contents.
58  //
59  // Filter syntax and the default page size are implementation choices; this
60  // example schema does not define them.
61  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {
62    option (google.api.http) = {
63      get: "/v1/users"
64    };
65    option idempotency_level = NO_SIDE_EFFECTS;
66  }
67 
68  // Create a user.
69  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse) {
70    option (google.api.http) = {
71      post: "/v1/users"
72      body: "user"
73      additional_bindings: {
74        put: "/v1/users/{user.id}"
75        body: "user"
76      }
77    };
78  }
79 
80  // Stream user change events. Intended for internal projectors.
81  rpc WatchUsers(ListUsersRequest) returns (stream GetUserResponse) {}
82}
83 