Rest 가이드

Rest URL 정의 가이드

다음은 한 엔티티에 대한 URL 기본 규칙이다. 사용자를 예로 들면 다음과 같다.

API 설명 HTTP 메서드 리소스 경로(URL)
모든 사용자 정보 얻기 GET /rest/v1/users
특정 한 사용자의 정보 얻기 GET /rest/v1/users/{id}
신규 사용자 정보 작성 POST /rest/v1/users
특정 한 사용자의 정보 업데이트 PUT /rest/v1/users/{id}
특정 한 사용자의 정보 삭제 DELETE /rest/v1/users/{id}
특정 값을 가지는 사용자가 존재하는지 조회 GET /rest/v1/users/exist?loginId=abc
사용자 유형 목록 조회 GET /rest/v1/user_types

데이터 전달은 메서드에 따라 다음과 같이 적용한다.

  • GET 방식에는 파라미터로 질의한다.
  • GET 외에는 데이터를 body 에 첨부한다.
  • PathVariable 로 지정되는 값은 해당 모델의 PK 로만 구성한다.
  • 모델이 특정 모델에 종속된다고 하여서 해당 모델 하위로 기술할 필요가 없다. PK 기반으로 독립적인 구성을 취한다. (위 방식중 사용자 유형 목록 조회 케이스)

PathVarialbe 사용에 대한 예시

예를 들어 Community : User = 1:n 관계를 가진다고 하여서 URL 을 /communities/{community_id}/users/{user_id} 로 구성하면 안된다. user 의 pk 가 상위 모델(여기에서 community) 과 연관이 없다면 독립적인 url(/users/{user}) 를 취한다. 그러나 user 의 pk 가 상위 모델에 종속될 경우(만약 user 의 pk 가 coummunity_id, join_order 와 같이 연관된 구성을 가질 경우)에는 /communities/{community_id}/users/{join_order} 와 같은 구성을 취할 수 있다.

Rest API Result

모든 Rest API 호출은 다음과 같은 json 형태를 가진다.

{
  "status": "OK",
  "success": true,
  "version": "1",
  "error": null,
  "data": []
}
속성명 설명 값 예시
success API 호출 성공 여부
status API 호출에 대한 상 OK, INTERNAL_SERVER_ERROR, 등
version API 버젼 1
error 호출이 실패했을 경우에 설정되는 에러 정보 하단 에러 정보 참조
data 호출이 성공했을 경우에 설정되는 결과 값 각 API 문서 참조

실패 에러 정보

success 가 false 일 경우 error 속성에 다음과 같이 설정된다.

{
  ...
  "error": {
    "type": "AUTHENTICATION",
    "code": "INVALIDATE_ACCESS_TOKEN",
    "message": "인증토근이 유효하지 않습니다.",
    "errorStack": null
  }
  ...
}

클라이언트(API 호출자)는 type 에 따라 적절한 에러처리를 해야한다.

type 에러여부 description
AUTHENTICATION 아님 인증 관련
BAD_PARAMETER 클라이언트 오류, 서버 오류 아님 API 입력에 필요한 파라미터가 잘못된 경우, 클라이언트 에러 처리 필요
MESSAGE 아님 사용자 액션 처리 오류. message 값을 사용자에게 출력한다
UNKNOWN 서버 오류 알 수 없는 서버 오류. 클라이언트에서는 서버 오류 발생에 대한 사용자에게 에러 안내조치를 시행한다

type 이 'AUTHENTICATION' 일 경우에 발생가능한 코드

code description
INCORRECT_LOGIN_ID_AND_PASSWORD 로그인 ID 와 패스워드가 일치하지 않을 경우, IDP 로그인 실패시에 발생
INVALIDATE_ACCESS_TOKEN 인증토큰이 옳바르지 않은 경우. 클라이언트 에러 처리
EXPIRED_ACCESS_TOKEN 인증토큰이 만료됨. 다시 로그인 화면을 유도해야한다
NO_PERMISSION 해당 API 를 수행할 권한이 없음

type 이 'BAD_PARAMETER' 일 경우에 발생가능한 코드

code description
REQUIRED_PARAMETER 필수 파라미터 누락
NOT_FOUND API 수행에 필요한 대상이 존재하지 않음

type 이 'MESSAGE' 일 경우에 발생가능한 코드

code description
DUPLICATE_LOGIN_ID IDP 로 회원가입시 이미 가입된 LOGIN_ID 가 있을 경우
DUPLICATE_CODE 코드 등록시 이미 등록된 코드가 있을 경우
SET_PARENT_TO_CHILDREN_ON_CATEGORY 트리에서 대상을 이동할 때, 대상의 자손으로 이동을 시도한 경우

type 이 'UNKNOWN' 일 경우에 발생가능한 코드

code description
UNKNOWN_SERVER_ERROR 알 수 없는 서버 오류. 사용자에겐 graceful 하게 에러 안내를 시행한다

results matching ""

    No results matching ""