An API call is a client request to a server, identified by an endpoint path and method, that asks for a resource or operation. HTTP calls can carry JSON or form data in the request body, while gRPC calls use defined request and response messages. section 8.2.3 section 10.1.1
A practical API call typically specifies:
- An HTTP method and route, such as PUT /games/{game_id}, describing the operation and target resource. section 8.2.3
- Input data, such as a JSON object containing a guess, or form values parsed from an HTTP request. section 8.2.3 section 11.4.2
- A handler that extracts parameters, decodes input, calls backend logic, and returns a response or redirect. section 11.3.1 section 11.4.2
- A stable request and response shape, especially for gRPC, so later fields can be added without breaking existing clients. section 10.1.1
Submitting a guess
A client can send PUT /games/123456 with {"guess":"hello"}. The handler decodes the body into a GuessRequest, rejects malformed input with HTTP 400, and processes the game identified by the path.
Listing 10.6 service.proto: Request and response
import "habit.proto"; #1
service Habits {
...
}
// CreateHabitRequest is the message sent to create a habit.
message CreateHabitRequest {
// Name of the new habit. Cannot be empty.
string name = 1;
// Frequency of the new habit. Will default to once per week.
optional int32 weekly_frequency = 2; #2
}
// CreateHabitResponse is the response of the create endpoint.
message CreateHabitResponse {
Habit habit = 1;
}
Inspect a version-compatible gRPC request and response definition for creating a habit. section 10.1.1
