[1] API 반환 값 설계 및 구현

이용 도구 및 개발 환경

 JAVA, Spring boot, AWS, Intellj, RestDoc, Postman

 

나의 고민

저는 회사에서 Open API 형태로 다수의 국내 및 해외 기업에 서비스를 제공하고 있습니다.

백엔드 개발자로 운영을 하다보니 여러가지 포인트에서 개선하고 싶었고 구체적으로 다음과 같은 일을 진행했습니다.

 

1. 테스트 케이스 기반의 API 사용 명세 문서가 자동 생성 되어야 한다.

   Spring RestDocs 로 구현

2. 서버에서 정의한 에러코드 문서화

3. 그 외 기타 에러에 대해서도 처리 ( JSON parse error, req body validation error .. )

 

API 사용자가 서비스 이용시 에러가 발생하면 사용자는 반환된 에러코드를 또 다시 검색 해야하는 불편함이 있습니다.

여러 고민 끝에 다음과 같이 에러 코드를 반환했습니다.

 

호출 API, refresh token을 이용해 access token을 발급

POST {{api-address}}/accounts/refresh-token

 

API 에러 반환 값

{
    "errors": [
        {
            "code": "a1010",
            "message": "The refresh token does not exist.",
            "referedUrl": "http://api.company.com/api/accounts/refresh-token",
            "apiDocument": "https://developers.company.com/auth/api-guide.html"
        }
    ]
}

domain의 경우 문서 공개가 애매하여 company.com으로 처리했습니다.

 

errors : 해당 api 에서 발생한 n개의 예외에 대해 반환합니다.

code : 문서에 정의된 에러코드 입니다. 앞의 알파벳은 도메인 성격에 의한것입니다. 뒤의 숫자는 0000 부터 순차적으로 올라가거나 다른 에러코드와 중복되지 않도록 했습니다.

message : 해당 에러코드에 대한 간략한 메시지 입니다. 다국어가 가능합니다.

referedUrl : 해당 API 호출 주소 입니다.

apiDocument: 개발자가 해당 에러에 대해 처리 할 수 있도록 API 문서 링크를 전달 합니다.

 

---

요청값 Validation 실패시에는 다음과 같이 반환 하도록 구현 했습니다.

휴대전화 번호에 전달된 인증코드 매칭 확인 API

{
    "errors": [
        {
            "code": "e1005",
            "message": "Bad Request",
            "details": [
                {
                    "message": "must not be blank",
                    "field": "authCode"
                }
            ],
            "referedUrl": "http://api.company.com/api/accounts/verify-code",
            "apiDocument": "https://developers.company.com/auth/api-guide.html"
        }
    ]
}

authCode field 값은 값이 존재해야 하는데 보내지 않을 경우 반환되는 메시지 입니다.

---

JSON 파싱 에러에 대해서도 반환

{
    "errors": [
        {
            "code": "e1004",
            "message": "JSON Parsing Error",
            "referedUrl": "http://api.company.com/api/accounts/verify-code",
            "apiDocument": "https://developers.company.com/auth/api-guide.html"
        }
    ]
}

 

회사 내부의 모바일 개발자, 웹 개발자, 문서를 외부 업체에 전달하는 기술 영업 사원 분들께 해당 문서에 대해 설명 드리고

서비스를 제공하였을때 기존보다 문의 사항도 많이 줄어들었음을 체감 하였습니다.

 

 

---

API 성공 반환 값

{
    "code": 200,
    "status": true,
    "message": "OK",
    "data": {
        "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhaSI6MTkxMCwiZXhwIjoxNjM5MzQ3MDk5LCJpYXQiOjE2MzkyNjA2OTl9.CnBYFTVs9veKgA2sU9SuD4GmtfLuQMaxJ3Fcj1WMTv4"
    }
}

성공값은 위와 같습니다.

 

다음 문서에서는 실제 코드와 함께 해당 구현에 대해 설명하겠습니다.