API 개요

모닥불 서비스의 모든 API에 해당되는 공통 해당사항에 대해 서술한다.

API 규약 정의

API 자체는 기능별 그룹 단위로 분류되어 있으나, 여러 페이지에서 여러 API를 교차적으로 사용할 수 있다. 데이터 포맷은 JSON 기반으로 HTTP/REST API 기반으로 동작하며, 기본적으로 HTTP 프로토콜의 Status Code Rule에 따른다. 단, 보안성 및 서비스의 원활한 진행을 위해 일부 룰을 오버라이딩하여 모닥불 내의 규약을 재정의하였다..

상태 코드

Success

200, ...

{
    result:"success",
    # optional add
    reason:"~~~"
}

요청이 성공적으로 수행되었음을 뜻한다. 각 성공의 의미는 API 별로 달라질 수 있으나 공통적으로 다음과 같은 상황일 경우, 모두 200으로 취급한다.

• 서버가 처리할 수 있는 정상적인 값을 수신한 경우

• 해당 결과의 True, False와 상관없이 정상적인 작업을 수행한 경우

Bad Request

400, 405, 406, 422, ...

{
    result:"bad request"
}

기존 API 규약에 위반된 올바르지 않는 파라미터의 입력으로 발생한다.

• 필수적으로 필요한 인자 값을 전달받지 못한 경우

• 전달받은 인자 값의 포맷이 규약에 위반될 경우

• 규약에 맞지 않는 HTTP Method로 호출된 경우

Unauthorized

401, 403, ...

{
    result:"unauthorized"
    // or "admin only", ...
}

사용자 인증이 필요한 기능에서 해당 API의 인증 권한에 충족되지 않았거나 인증 자체를 수행하지 않았을 때 발생한다.

• 본인을 인증할 토큰 값 자체를 전송하지 않은 경우

• 해당 토큰 값이 유효하지 않은 경우

Resource Not Found

404

{
    result:"404 page"
}

클라이언트가 서버에 요청한 리소스를 찾을 수 없을 경우에 해당된다. 해당 리소스에는 URI, 첨부파일 등을 비롯한 서버의 모든 자원을 포함한다.

Internal Server Error

500, 502, 503, ...

{
    result:"fail"
}

서버가 해당 작업을 수행하던 내부 오류가 발생하였고, 유효한 결과 값을 건네줄 수 없음을 의미한다.

• 서버가 해당 값을 처리하는 도중 에러가 발생했다

• 해당 요청 방법은 서버에서 지원하지 않는다.

• 서버가 잘못된 게이트웨이로 응답을 수신했다.

• 서버가 요청을 처리할 준비가 아직 되지 않았다.