API 개요

세자보 백엔드 API에 대하여 서술한다.

API 자체는 기능별 그룹 단위로 분류되어 있으나, 여러 페이지에서 여러 API를 교차적으로 사용할 수 있다.

데이터 포맷은 JSON이며, 모든 API 결과는 다음과 같은 공통적인 특징을 가지고 있다.

요청에 대한 응답을 성공했을 경우 (200)

모든 요청에 대한 응답의 성공 여부는 result Key 값을 통해 확인할 수 있다. 단 여기서의 "success"가 반드시 의도대로의 실행을 수행했다는 뜻은 아니며, 요청에 대한 처리는 완료했지만 입력 조건이 충족되지 않아 API 자체는 실행되지 않았을 수도 있다.

단, 실행되지 않더라도 사용자가 원하는 명령 수행에는 문제가 없을 경우, 이것을 "success"로 취급한다.

{
    "result":"success",
    ["comment":"~~~"]
    ...
    ...
}

입력 조건이 충족되지 않아 적절한 액션을 취할 수 없을 경우 (200)

API 기능을 수행하기 위한 조건이 충족되지 않아 실패한 경우이다. 이 경우에도 result Key 값을 통해 그 요인을 확인할 수 있으며, "success" 이외의 값을 확인하게 된다.

{
    "result":"원인"
    // Password Incorrect
    // Answer not matched
}

허용되지 않는 접근 방식 (400, 403, ...)

조건 자체가 통상적인 수단으로는 얻을 수 없는 입력 값일 경우, 해당 결과를 반환한다. 해당 에러를 반환하는 요인에는 존재하지 않는 데이터를 대상으로 하거나, 유효하지 않는 토큰으로 인증 요청을 할 경우 등이 있다.

{
    "result":"원인"
    // bad request
    // Admin Only
}

내부 서버 에러 (500, 503,...)

API가 정상적으로 작동하지 않으며, 유효한 입력 값을 넣어도 정상적인 결과를 반환받을 수 없다.

{
    "result":"fail"
}