Skip to content

Commit

Permalink
(WIP) 기존 MDX 문서들 린트 수정
Browse files Browse the repository at this point in the history
  • Loading branch information
@XiNiHa
XiNiHa committed Mar 21, 2024
1 parent 0dc35e1 commit 443fdaa
Show file tree
Hide file tree
Showing 306 changed files with 11,717 additions and 12,631 deletions.
125 changes: 50 additions & 75 deletions src/content/api-section-description/v1auth.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,114 +1,89 @@
import ApiLink from "~/layouts/rest-api/misc/ApiLink";
import Details from "~/components/gitbook/Details.astro";
import Figure from "~/components/Figure.astro";
import Details from "~/components/gitbook/Details.astro";
import Hint from "~/components/Hint.astro";
import ApiLink from "~/layouts/rest-api/misc/ApiLink";

import getTokenImage from "./_assets/v1auth/get-token.png";
import merchantInfoImage from "./_assets/v1auth/merchant-info.png";
import reuseImage from "./_assets/v1auth/reuse.svg";
import tierImage from "./_assets/v1auth/tier.png";
import useImage from "./_assets/v1auth/use.png";

포트원 API를 호출할 때는 **액세스 토큰**을 `Authorization` 헤더에 넣어주어야 합니다.\
액세스 토큰은 <ApiLink client:visible basepath="/api/rest-v1" section="auth" method="post" path="/users/getToken" apiName="access_token 발급 API" />를 호출해서 발급받을 수 있습니다.

액세스 토큰 발급 API를 호출하려면 **API 키**와 **API 시크릿**을 인자로 넣어주어야 합니다.

<Details>
<p slot="summary">API 키와 API 시크릿 확인하기</p>

1. [관리자 콘솔 `상점・계정 관리` 화면](https://admin.portone.io/merchant) 접속
2. `내 식별코드・API Keys` 버튼 클릭

import merchantInfoImage from "./_assets/v1auth/merchant-info.png";

<Figure
src={merchantInfoImage}
caption="API 키와 API 시크릿은 관리자 콘솔 → 상점・계정 관리 메뉴 → 내 식별코드・API Keys 모달을 열어서 확인하실 수 있습니다"
/>
<p slot="summary">API 키와 API 시크릿 확인하기</p>

<Hint style="danger">
**API 시크릿은 절대로 외부에 노출되어서는 안되는 값**입니다.\
실제 구현에서 액세스 토큰 발급은 꼭 서버사이드에서 해주세요.
1. [관리자 콘솔 `상점・계정 관리` 화면](https://admin.portone.io/merchant) 접속
2. `내 식별코드・API Keys` 버튼 클릭

</Hint>
<Figure src={merchantInfoImage} caption="API 키와 API 시크릿은 관리자 콘솔 → 상점・계정 관리 메뉴 → 내 식별코드・API Keys 모달을 열어서 확인하실 수 있습니다" />

<Hint style="danger">
**API 시크릿은 절대로 외부에 노출되어서는 안 되는 값**입니다.\
실제 구현에서 액세스 토큰 발급은 꼭 서버 사이드에서 해주세요.
</Hint>
</Details>

<Details>
<p slot="summary">액세스 토큰 발급 받기</p>
<p slot="summary">액세스 토큰 발급 받기</p>

<ApiLink
client:visible
basepath="/api/rest-v1"
section="auth"
method="post"
path="/users/getToken"
apiName="access_token 발급 API"
/> 호출
<ApiLink client:visible basepath="/api/rest-v1" section="auth" method="post" path="/users/getToken" apiName="access_token 발급 API" /> 호출

import getTokenImage from "./_assets/v1auth/get-token.png";

<Figure
src={getTokenImage}
caption="/users/getToken API를 호출해서 액세스 토큰을 발급받습니다"
/>

<Hint style="info">
포트원 REST API 서버는 **Google Public NTP**의 시간과 동기화되고 있습니다.

</Hint>
<Figure src={getTokenImage} caption="/users/getToken API를 호출해서 액세스 토큰을 발급받습니다" />

<Hint style="warning">
하위 가맹점 연동을 할 경우 액세스 토큰을 발급받을 때 **Agent 계정**의 **API 키** 와 **API 시크릿**을 사용해야 합니다.
<Hint style="info">
포트원 REST API 서버는 **Google Public NTP**의 시간과 동기화되고 있습니다.
</Hint>

[Agency & Tier 란?](/docs/ko/tip/agency-and-tier)

</Hint>
<Hint style="warning">
하위 가맹점 연동을 할 경우 액세스 토큰을 발급받을 때 **Agent 계정**의 **API 키** 와 **API 시크릿**을 사용해야 합니다.

[Agency & Tier 란?](/docs/ko/tip/agency-and-tier)
</Hint>
</Details>

<Details>
<p slot="summary">액세스 토큰 사용하기</p>

발급받은 액세스 토큰은 다른 API를 호출할 때\
`Authorization` 헤더에 `Bearer <액세스 토큰>` 형식의 값을 넣어주면 됩니다.

자세한 내용은 [MDN - HTTP 인증 문서](https://developer.mozilla.org/ko/docs/Web/HTTP/Authentication)를 참고해주세요.
<p slot="summary">액세스 토큰 사용하기</p>

import useImage from "./_assets/v1auth/use.png";

<Figure src={useImage} />
발급받은 액세스 토큰은 다른 API를 호출할 때\
`Authorization` 헤더에 `Bearer <액세스 토큰>` 형식의 값을 넣어주면 됩니다.

<Hint style="warning">
하위 가맹점 연동을 할 경우 포트원 API 호출시 `Tier` 헤더에 하위 가맹점 티어 코드를 입력해야 합니다.
자세한 내용은 [MDN - HTTP 인증 문서](https://developer.mozilla.org/ko/docs/Web/HTTP/Authentication)를 참고해주세요.

[Agency & Tier 란?](/docs/ko/tip/agency-and-tier)

import tierImage from "./_assets/v1auth/tier.png";
<Figure src={useImage} />

<Figure src={tierImage} />
<Hint style="warning">
하위 가맹점 연동을 할 경우 포트원 API 호출시 `Tier` 헤더에 하위 가맹점 티어 코드를 입력해야 합니다.

</Hint>
[Agency & Tier 란?](/docs/ko/tip/agency-and-tier)

<Figure src={tierImage} />
</Hint>
</Details>

<Details>
<p slot="summary">액세스 토큰 만료기한 연장</p>
<p slot="summary">액세스 토큰 만료기한 연장</p>

만료된 액세스 토큰으로 API를 호출하면 `401 Unauthorized` 응답을 받습니다.\
액세스 토큰의 만료기한은 발행시간부터 **30분**입니다.

- 기존 액세스 토큰이 만료되기 전 <ApiLink client:visible basepath="/api/rest-v1" section="auth" method="post" path="/users/getToken" apiName="access_token 발급 API" />를 다시 호출했을 경우
- 기존 액세스 토큰이 반환됩니다.\
**만료기한이 1분 안쪽으로 남았을 때** 요청했다면 기존 액세스 토큰의 만료시간이 **5분 연장**됩니다.
- 기존 액세스 토큰이 만료된 다음 <ApiLink client:visible basepath="/api/rest-v1" section="auth" method="post" path="/users/getToken" apiName="access_token 발급 API" />를 다시 호출했을 경우
- 새로운 액세스 토큰이 반환됩니다.

import reuseImage from "./_assets/v1auth/reuse.svg";
만료된 액세스 토큰으로 API를 호출하면 `401 Unauthorized` 응답을 받습니다.\
액세스 토큰의 만료 기한은 발행시간부터 **30분**입니다.

<Figure src={reuseImage} />
- 기존 액세스 토큰이 만료되기 전 <ApiLink client:visible basepath="/api/rest-v1" section="auth" method="post" path="/users/getToken" apiName="access_token 발급 API" />를 다시 호출했을 경우
- 기존 액세스 토큰이 반환됩니다.\
**만료 기한이 1분 안쪽으로 남았을 때** 요청했다면 기존 액세스 토큰의 만료 기한이 **5분 연장**됩니다.

<Hint style="info">
액세스 토큰의 재사용과 만료기한 5분 연장 동작방식은 다음과 같은 상황을 고려해서 설계되었습니다.
- 기존 액세스 토큰이 만료된 다음 <ApiLink client:visible basepath="/api/rest-v1" section="auth" method="post" path="/users/getToken" apiName="access_token 발급 API" />를 다시 호출했을 경우
- 새로운 액세스 토큰이 반환됩니다.

- 한 가맹점에서 여러 대의 웹서버가 동시에 경쟁적으로 REST API(`/users/getToken`)를 호출하는 상황
- 한 가맹점에서 여러 대의 웹서버가 시간 동기화 되어있지 않은 상황
<Figure src={reuseImage} />

</Hint>
<Hint style="info">
액세스 토큰의 재사용과 만료 기한 5분 연장 동작 방식은 다음과 같은 상황을 고려해서 설계되었습니다.

- 한 고객사에서 여러 대의 웹서버가 동시에 경쟁적으로 REST API(`/users/getToken`)를 호출하는 상황
- 한 고객사에서 여러 대의 웹서버가 시간 동기화 되어있지 않은 상황
</Hint>
</Details>
1 change: 1 addition & 0 deletions src/content/blog/2024-02/v2-oom.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ thumbnail: ./_assets/v2-oom/0.png
---

import Figure from "~/components/Figure.astro";

import image0 from "./_assets/v2-oom/0.png";
import image1 from "./_assets/v2-oom/1.png";
import image2 from "./_assets/v2-oom/2.png";
Expand Down
10 changes: 5 additions & 5 deletions src/content/blog/2024-02/v2-zio.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -519,12 +519,12 @@ ZIO는 그러한 조건에 잘 부합하는 Effect System이었고 현재까지
이러한 요구사항을 만족하기 위해 신중한 고민을 거쳐 의사결정을 했고, 그렇게 탄생한 포트원 V2 모듈은 수많은 디지털 커머스 회사들과 함께할 준비를 마쳤습니다.
포트원 V2에서는 커머스 회사들이 결제와 관련된 고민을 덜 수 있도록 멋진 기능들을 많이 출시할 예정이니, 앞으로 포트원 V2 모듈의 행보를 지켜봐주세요!

[scala]: \(https://scala-lang.org/\)
[scala]: https://scala-lang.org/

[why-fp-matters]: \(https://www.cs.kent.ac.uk/people/staff/dat/miranda/whyfp90.pdf\)
[why-fp-matters]: https://www.cs.kent.ac.uk/people/staff/dat/miranda/whyfp90.pdf

[for-comprehension]: \(https://docs.scala-lang.org/tour/for-comprehensions.html\)
[for-comprehension]: https://docs.scala-lang.org/tour/for-comprehensions.html

[ast]: \(https://en.wikipedia.org/wiki/Abstract_syntax_tree\)
[ast]: https://en.wikipedia.org/wiki/Abstract_syntax_tree

[zio]: \(https://zio.dev/\)
[zio]: https://zio.dev/
Loading

0 comments on commit 443fdaa

Please sign in to comment.