REST API 시작하기¶

API를 바로 사용할 수도 있지만, .env파일의 환경설정 값을 확인하고 시작하는 것이 좋습니다.

• JWT SECRET_KEY 설정 (필수)
• API 활성화/비활성화
• API 버전 확인
• JWT 토큰 만료시간 설정

1. 환경설정¶

JWT SECRET_KEY 설정¶

ACCESS_TOKEN_SECRET_KEY, REFRESH_TOKEN_SECRET_KEY 값을 임의의 문자열 로 변경합니다.

• 예시: secretkey(기본값) -> 51dyl421mvcz119djkfz(임의의 문자열)

$ openssl rand -hex 32
3da8c33461f838b851e0a6016856f4c6461e889852fc50f636ace1b01398cfac

API 활성화/비활성화¶

USE_API 값이 True로 설정되어 있는지 확인합니다.

True : API 활성화 (기본값), False : API 비활성화 (1)

1. API 요청에 대해 응답하지 않습니다.

API 버전 확인¶

API_VERSION 값이 사용하려는 API 버전과 일치하는지 확인합니다.

• 예시: v1 (기본값)

JWT 토큰 만료시간 설정¶

ACCESS_TOKEN_EXPIRE_MINUTES, REFRESH_TOKEN_EXPIRE_MINUTES 값을 확인합니다.

• ACCESS_TOKEN_EXPIRE_MINUTES : Access Token 만료 시간 (기본값: 30분)
• REFRESH_TOKEN_EXPIRE_MINUTES : Refresh Token 만료 시간 (기본값: 14일(60 * 24 * 14 분))

2. API 요청¶

API 문서¶

그누보드6 API에 요청할 수 있는 엔드포인트는 자동으로 생성되는 문서에서 확인 가능합니다.
아래 예제에서는 Swagger UI를 사용하여 API를 요청하는 방법을 설명합니다.

처음 접속하면 아래와 같은 화면이 나타납니다.

인증¶

일부 API요청에는 JWT 토큰을 사용한 인증이 필요합니다.
인증이 필요한 API는 자물쇠가 표시됩니다.

인증 헤더 구성¶

인증이 필요한 API를 요청할 때는 '인증 > Access/Refresh Token 발급' API를 통해 발급받은 Access Token을 사용하여 요청합니다.
발급받은 Access Token과 Bearer 값을 포함한 Authorization 속성을 헤더에 포함하여 요청합니다.

• 예시 : Authorization: Bearer {Access Token}

Swagger UI¶

1. Swagger UI에서 인증 과정을 진행하기 위해 Authorize 버튼 또는 자물쇠를 클릭합니다.

2. 인증정보 화면이 나타나면 username과 password를 입력하고 Authorize 버튼을 클릭합니다.
   계정정보는 그누보드6 템플릿에서 사용하는 계정과 동일합니다.

3. 인증이 완료되면 아래와 같은 화면을 확인할 수 있습니다.

4. 인증이 완료되면 자물쇠 아이콘이 변경되고 API를 요청할 수 있습니다.

예제¶

아래 예제는 GET방식으로 /api/v1/members/me를 호출하는 예제입니다.

1. 자바스크립트(JQuery)¶

인증¶

JWT (ACCESS TOKEN)을 발급받기 위한 POST방식으로 요청을 보냅니다.

var form = new FormData();
form.append("grant_type", "password");
form.append("username", "{ID}");
form.append("password", "{PASSWORD}");

var settings = {
    "url": "http://127.0.0.1:8000/api/v1/token",
    "method": "POST",
    "timeout": 0,
    "headers": {},
    "processData": false,
    "mimeType": "multipart/form-data",
    "contentType": false,
    "data": form
};

$.ajax(settings).done(function (response) {
    console.log(response);
});

인증결과¶

• 결과값에서 access_token, refresh_token을 확인할 수 있습니다.
• 토큰 값은 localStorage, Session, Cookie에 저장하여 사용합니다.

{
    "access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJramhpZWQiLCJpc3MiOiJnNl9yZXN0X2FwaSIsImlhdCI6MTcxNzU3NzYyNCwiZXhwIjoxNzE3NjExODI0fQ.KH_e0S8u0Gv6ZgajKUXbbMsDsDmb-SyuvFANvJDJHh4",
    "access_token_expire_at":"2024-06-05T18:23:44.779668",
    "refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnNl9yZXN0X2FwaSIsImlhdCI6MTcxNzU3NzYyNCwiZXhwIjoxNzE4ODE5NjI0fQ.5LkmJEjh_XQr85686ZQFaS-4qhOn7i4aqLQJrC-5KkY",
    "refresh_token_expire_at":"2024-06-19T17:53:44.779668",
    "token_type":"Bearer"
}

API요청¶

access_token을 header에 추가해서 API요청을 보냅니다.

• headers에 Authorization: Bearer {access_token}을 추가합니다.

var settings = {
    "url": "http://127.0.0.1:8000/api/v1/members/me",
    "method": "GET",
    "timeout": 0,
    "headers": {
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJramhpZWQiLCJpc3MiOiJnNl9yZXN0X2FwaSIsImlhdCI6MTcxNzU3NzYyNCwiZXhwIjoxNzE3NjExODI0fQ.KH_e0S8u0Gv6ZgajKUXbbMsDsDmb-SyuvFANvJDJHh4"
    },
};

$.ajax(settings).done(function (response) {
    console.log(response);
});

결과¶

2. Postman¶

인증/결과¶

Postman에서 JWT (ACCESS TOKEN)을 발급받기 위해 POST방식으로 요청을 보냅니다.

• Body탭에서 grant_type, username, password항목을 추가하고 해당 정보들을 추가합니다.

API요청/결과¶

• Headers 탭에서 Authorization 항목을 추가합니다.
• Bearer : {access_token} 형식으로 값을 입력 후 API요청을 보냅니다.