원문: https://qiita.com/suin/items/f7ac4de914e9f3f35884#%E3%81%BE%E3%81%A8%E3%82%81
에러 내용의 비교
각 서비스들의 API가 제공하고 있는 정보를 표에 정리하였다.
이번에 조사한 범위에서는 모든 서비스가 사람이 읽고 이해할 수 있는 형식의 메세지를 반드시 에러에 포함시키고 있었다.
에러 코드는 프로그램이 그 에러를 다루기 쉽도록 int 또는 string이었다. 또한 에러 코드를 응답하는 API 중에는 에러 코드 일람표를 제공하고 있는 섭시그와 그렇지 않은 서비스가 있었다. 클라이언트로써는 에러코드 일람표가 있으면 적절한 에러 핸들링을 프로그래밍할 수 있는 것이 가능하기 때문에 API 프로바이더가 일람표를 공개해 두면 좋다고 생각한다.
서비스의 성질에 따라 복수에러를 응답할수 있는 편이 좋을지도 모르지만, 클라이언트가 애플리케이션에서 입력란이 복수 있는 UI에서는 한 번에 복수의 에러를 파악할 수 있는 편이 좋은 유저 체험이 되는 경우가 있다.
필드명 비교
각각의 서비스에서 사용되고 있는 필드명을 정리한 표이다.
메세지에 대해서는 많은 서비스가 'message' 를 채용하고 있었다. 에러 코드에 대해서는, 'code' 가 가장 많고, 'type' 과 이름을 붙이는 경우도 있었다. 복수에러를 응답할 가능성이 있는 서비스에서는 'errors' 와 복수형의 필드명을 쓰고 있었다. 상태 코드에 대해서는 'code' 또는 'status' 가 사용되고 있었다. 상세URL을 제공하고 있는 서비스는 이번 조사범위에서는 적었지만 'url', 'rel_url', 'more_info' 이 사용되고 있었다.
API를 설계할 때, 다른 서비스에서 사용되고 있는 네이밍을 모방하면 다른 API의 경험이 있는 개발자라도 그 필드가 무엇을 표현하고 있는지 이해하기 쉽지 않을까?
마지막으로 조사하고 있던 API 문서에 에러 응답 바디에 대해서 설명을 하고 있는 서비스와 그렇지 않은 서비스가 있는 것을 알았다. 개발자로써는 API가 어떤 형식의 에러를 응답할지를 알기 쉽게 적혀 있으면 클라이언트를 구현하기 쉽다. 또한, 문서에는에러에 포함되는 필드명의 리스트나 표 뿐만 아니라, 구체적으로 JSON의 예시모 있으면 친절하게 느껴진다.
에러 응답에서 고려하고 싶은 것
이상의 조사를 끝내고, 제 나름대로 에러를 표현할 때 고려하고 싶은 것을 정리하였다.
- 에러 메세지: 개발자가 읽고 알수 있는 메세지를 넣는다.
- 에러 코드: 클라이언트의 프로그램이 에러 핸들링의 단서가 되는 정보를 준다. 추가적으로, API 문서에서는 에러 코드의 일람을 공개한다.
- 복수 에러: 서비스에 따라 case by case 이지만, 복수의 에러를 표현할 수 있도록 되어 있다.
- 상세 URL: 공개 API에서 문서가 정리되어 있다면, 개발자가 구글링하는 수고를 덜 수 있다.
- 일관성: 어떤 엔드포인트에서도 같은 구조의 JSON이다.
- 심플: 복잡한 구조가 아닌, nest가 얕은 JSON이 클라이언트가 복잡한 형태를 정의하지 않고 끝난다.
결론
Web API에서 에러를 어떻게 표현하면 좋을지, 15개의 서비스의 예를 보면서 생각해 보았다. 어떤 서비스라도 공통적인 부분이 있는 반면, 독자적인 부분이 있는 API도 있었다.
서버 개발자로 프로젝트하면서 에러 응답 스펙 정하는 게 고민이었는데 사례들 모아서 정리해주신 게 있었네요 감사합니다!