2장. Restfull API 구성

• Gate Token 개념
• 다보리 API 설계의 기본 지식
• PAP(pick-act-page) API 설명

Gate Token 개념

인증 & OAuth 2.0

인증이란 특정 사용자가 본인임을 확인하는 절차를 의미합니다. 일반적으로 아이디와 비밀번호가 일치하면 해당 사용자가 본인이라고 판단할 수 있습니다. 예를 들어, 다보리에 로그인할 때 다보리 계정의 아이디와 비밀번호를 입력하여 본인 여부를 확인하는 방식입니다.

하지만,  다보리 오픈API를 활용하여 개발한 애플리케이션에서 사용자가 다보리 계정의 아이디와 비밀번호를 직접 입력하도록 하면 보안상의 위험이 발생할 수 있습니다. 이를 방지하기 위해, 사용자가 제 삼자가 만든 애플리케이션이 아닌 **공식 인증 서비스(예: 네이버 로그인 페이지)**에서 직접 인증을 진행하고, 그 결과를 애플리케이션에 전달하는 방식이 필요합니다.

이러한 인증 방식을 체계적으로 정리한 표준이 OAuth이며, 다보리 오픈API는 OAuth 2.0 프로토콜을 적용하여 안전한 인증 서비스를 제공하고 있습니다.

Gate Token

dabory sso(OAuth2 기반)을 통해 사용자가 인증되면 이후 GateToken을 사용하여 API 서버와 DB에 연동할 수 있습니다. GateToken 자체는 사용자 인증을 담당하지 않고, 로그인 이후 인증된 사용자의 권한을 기반으로 API 및 DB 접근을 관리하는 역할을 합니다.

다보리 Frontend에서는 로그인 체크 이전에 session에 저장된 gatetoken을 check합니다. 만약 gatetoken이 존재하지 않는다면 main_api server로 부터 gatetoken을 발급받습니다. 즉 gatetoken은 app등록시 입력된 db 접근정보와 api server와의 정상적인 연동 권한을 갖췄는지 체크하기 위해 사용되는 암호화된 토큰입니다.

api 서버로부터 반환받은 GateToken은 프론트엔드 session에 저장됩니다. 이 session은 권한이 필요한 모든 프론트엔드 요청의 header에 포함됩니다.

다보리 API 설계의 기본 지식

HTTP Method 및 보안성:

• 다보리 ERP의 모든 API는 단순성과 보안성을 고려하여 POST method만 사용합니다.
• 이는 데이터 변경 및 전송의 안정성을 보장할 수 있습니다.

DaborySSO 및 환경 변수:

• DaborySSO를 사용하여 API 서버에 인증 및 권한 관리를 권장하지만  필요에 따라 Key Pair를 API 서버의 환경 변수에 저장하여 SSO 서버와 독립적으로 사용할 수 있습니다.

GateToken:

• 모든 API 요청은 API 서버로부터 반환받은 GateToken을 포함해야 합니다. 이를 통해 인증 및 권한 부여가 이루어집니다.
• GateToken은 타켓 DB의 접근 정보를 PKI 암호화한 BeforeBase64 Key로만 발급받을 수 있습니다. 이는 데이터 보안을 강화합니다.
• 모든 Frontend Server는 ClientID 값을 가집니다. 이는 DaborySSO에서 App 레코드를 생성하는 과정에서 생성됩니다.
• Client(Frontend)의 GateToken은 API 서버의 메모리 DB에 저장됩니다. 또한 유효기간 설정이 가능합니다. 이를 통해 인증된 클라이언트만이 API를 사용할 수 있도록 합니다.

이러한 설계 원칙을 준수하여 안전하고 효율적인 API 시스템을 구축할 수 있습니다.

PAP(pick-act-page) API 설명

PAP API

PAP(pick-act-page) API는 다보리 컴포저블 앱에서 개별 Table 단위의 데이터 처리를 위한 API 구조를 정의하는 방법입니다. 

이 API의 구조는 기본적으로 단일 데이터 추출(Pick), 실행(Action), 다수의 row 추출 (Page) 세 가지 api를 포함하고 있습니다.

 pick-api

WHERE절에 유니크한 값인 Id를 포함시켜 단일데이터 및 다수의 레코드를 추출하는 api입니다.

php 사용예시

$itemPick = $this->callApiService->callApi([
  'url' => 'item-pick',
  'data' => [
    'Page' => [
                 ['UpdatedMd5' => $updatedMd,]
    ],
  ],
  'headers' => [
  'GateToken' => $this->gateToken['main']
  ]
]);

JavaScript 사용예시

const response = await axios.post('/ajax/get-data', {
  url: 'item-pick',
  data: {
    Page: [
            { Id:  parseInt(window.User['SgroupId']) } 
    ]
  }
});

 act-api

Insert, Update, Delete와 같은 데이터 작업을 수행합니다. Id의 값에 따라 Insert(0), Update(양수), Delete(음수)로 구분합니다.

만약 Id값이 0보다 큰 양수라면 해당 Id값에 해당하는 데이터를 Update합니다. 

Delete는 다른 필드 없이 ID 값만으로 처리할 수 있습니다.

php 사용예시

// insert
$itemAct = $this->callApiService->callApi([
            'url' => 'item-act',
            'data' => [
                'Page' => [
                    [
                        'Id' => 0, // 0 : insert, 양수: update, 음수 : delete
                        'IgroupId' => 526,
                        'ItemCode' => Str::limit($linkproMd5, 21, ''),
                        'ItemSlug' => $linkproMd5,
                        'ItemName' => $scrap['ItemName'],
                        'SalesPrc' => (string)$scrap['SalesPrice'],
                    ]
                ],
            ],
            'headers' => [
                'GateToken' => $this->gateToken['main']
            ]

// update
$itemAct = $this->callApiService->callApi([
            'url' => 'item-act',
            'data' => [
                'Page' => [
                    [
                        'Id' => 4, // 0 : insert, 양수: update, 음수 : delete
                        'IgroupId' => 526,
                        'ItemCode' => Str::limit($linkproMd5, 21, ''),
                        'ItemSlug' => $linkproMd5,
                        'ItemName' => $scrap['ItemName'],
                        'SalesPrc' => (string)$scrap['SalesPrice'],
                    ]
                ],
            ],
            'headers' => [
                'GateToken' => $this->gateToken['main']
            ]

                                          
// delete
$itemAct = $this->callApiService->callApi([
            'url' => 'item-act',
            'data' => [
                'Page' => [
                    [ 'Id' => -4 ] // 0 : insert, 양수: update, 음수 : delete     
                ],
            ],
            'headers' => [
                'GateToken' => $this->gateToken['main']
            ]

const response = await axios.post('/ajax/get-data', {
        url: 'item-act',
        data: {
          Id : 0,
          ItemCode: $(item_form).find('#item-code-txt').val(),
          IgroupId: Number($(item_form).find('#igroup-id-txt').data('id')),
          ItemName: $(item_form).find('#item-name-txt').val(),
          SubName: $(item_form).find('#sub-name-txt').val(),
          ItemSlug: $(item_form).find('#item-slug-txt').val(),
        }
});

const response = await axios.post('/ajax/get-data', {
        url: 'item-act',
        data: {
          Id : 3,
          ItemCode: $(item_form).find('#item-code-txt').val(),
          IgroupId: Number($(item_form).find('#igroup-id-txt').data('id')),
          ItemName: $(item_form).find('#item-name-txt').val(),
          SubName: $(item_form).find('#sub-name-txt').val(),
          ItemSlug: $(item_form).find('#item-slug-txt').val(),
        }
});

const response = await axios.post('/ajax/get-data', {
        url: 'item-act',
        data: {Id : -3}
});

 page-api

하나의 SELECT 쿼리로 테이블의 레코드를 2차원 리스트 형태로 가져옵니다. 

Query, Asc, Desc, Limit, Offset 등의 파라미터를 통해 request할 data의 필터링을 설정합니다. 

php 사용예시

$this->callApiService->callApi([
  'url' => 'app-guest-page',
  'data' => [
    'PageVars' => [
      'Query' => "app_name = '$appName' and is_on_use = 1",
      'Limit' => 1,
    ]
  ],
'headers' => [
  'GateToken' => $this->gateToken['main']
]

JavaScript 사용예시

let response = await get_api_data('setting-search-page', {
  QueryVars: {
    QueryName: 'igroup',
    FilterName: 'dbr_igroup.id',
 },
  PageVars: {
    Limit: 9999,
    Offset: 0,
  }
})

// get_api_data(url, data)