요청 만들기¶

이 장을 읽고 나면

HTTP method와 path를 고르고, query·header·요청별 timeout으로 한 요청을 외부 API의 요구에 맞게 구성할 수 있다.

request builder는 client에서 method를 선택할 때 생기며, 종결자로 응답을 요청하기 전까지 요청의 모양을 누적한다. 종결자(terminator)는 builder 구성을 끝내고 실제 요청을 제출해 응답 형태를 정하는 마지막 호출이다. path는 base URL 뒤에 붙는 /로 시작하는 경로다.

1. method와 path 선택¶

HTTP client는 GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS의 일곱 method를 제공한다. GET은 읽기에, POST는 새 작업이나 resource 생성에 사용한다. C++에서는 keyword와 겹치는 DELETE를 delete_로 표기한다.

path가 /로 시작하지 않으면 요청을 보내지 않고 protocolError로 끝난다. base URL과 path를 한 요청 안에서 섞지 않고, 다른 base URL이 필요하면 별도 client 또는 one-shot을 사용한다.

2. query·header·timeout 추가¶

query는 name과 value를 URL-encoding하여 누적한다. header는 그 요청에만 적용되며 같은 이름의 client 기본 header보다 우선한다. 요청별 timeout은 client의 기본 timeout을 그 요청에서만 대체한다.

↗ 크게 보기

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}`);

이 코드는 일반 API와 관리 API에 서로 다른 base URL을 사용하고, 요청별 header·timeout·query를 더한 뒤 typed 응답에서 status와 변경된 weight를 읽는다.

3. 요청마다 달라지는 값¶

요청마다 달라지는 인증 정보, 추적 ID, query와 timeout은 request builder에 둔다. 여러 요청에서 항상 같은 header나 인증 정보는 client를 만들 때 설정한다. timeout은 한 시도의 시간 경계이며, retry를 설정하면 각 시도에 적용된다. 재시도와 응답 상태 규칙은 redirect·retry·cookie와 응답 처리 규칙에서 다룬다.

다음 장¶

요청 본문에서 JSON, form, multipart body를 붙인다.