Making Requests¶

Contents | Previous: Installation and the First Request | Next: Request Bodies

After reading this chapter

You can choose an HTTP method and path, then shape one request for an external API with queries, headers, and a per-request timeout.

A request builder is created when a method is selected from the client. It accumulates the request shape until a terminator asks for a response. A terminator is the final call that finishes the builder, submits the request, and selects the response form. A path starts with / and follows the base URL.

1. Methods and Paths¶

The HTTP client provides the seven methods GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS. GET reads a resource; POST starts work or creates one. C++ spells DELETE as delete_ because of its keyword.

A path that does not start with / ends with protocolError before a request is sent. One request keeps its base URL and path separate. Another base URL uses a separate client or a one-shot.

2. Queries, Headers, and a Timeout¶

A query accumulates names and values after URL encoding. A header applies only to that request and overrides a client default header with the same name. A per-request timeout replaces the client's default timeout only for that request.

↗ 크게 보기

const status = await client
  .get('/ops/nodes/game-server-1/status')
  .header('x-trace-id', 'tutorial-1')
  .timeout(5000)
  .submit<{ processId: number }>();
// The admin URL is different, so this one-shot request uses a separate client.
const weight = await ZLinkHttpClient.create(adminBaseUrl)
  .basicAuth('ops', 'tutorial-admin')
  .post('/admin/channels/profile/weight')
  .query('value', '2')
  .submit<WeightResult>();
console.log(`request shaping: status ${status.status} weight ${weight.body.weight}`);

The code uses separate base URLs for the regular and administrative APIs, adds a per-request header, timeout, and query, then reads the status and changed weight from typed responses.

3. Values That Change Per Request¶

Request-specific credentials, trace IDs, queries, and timeouts belong on the request builder. Headers and credentials that apply to every request belong on the client. A timeout is the time boundary for one attempt, and retry applies it to each attempt. Retry and response-status rules are covered in Redirect, Retry, and Cookies and Response Rules.

Next Chapter¶

Request Bodies adds JSON, form, and multipart bodies.