API 명세서 작성 규칙(convention)

[개요]

프로젝트를 진행하며 Front-end와 Back-end 사이에 주고 받을 API 명세서를 설계하게 되었다. 두 번의 웹 서비스 프로젝트를 거치며 적당하다 생각하는 정도를 담아 규칙 등을 이유와 함께 정리하려 한다.

[본문]

---

HTTP status code

JWT 등 토큰이 만료 되었거나 유효하지 않은 토큰일 시 401(Unauthorized)를 응답한다.

HTTP(하이퍼텍스트 전송 프로토콜) 401 Unauthorized 응답 상태 코드는 요청된 리소스에 대한 유효한 인증 자격 증명이 없기 때문에 클라이언트 요청이 완료되지 않았음을 나타냅니다. 
이 상태 코드는 사용자에게 인증 자격 증명을 입력하라는 메시지를 표시한 후 클라이언트가 리소스를 다시 요청할 수 있는 방법이 포함된 HTTP WWW-Authenticate (en-US) 응답 헤더와 함께 전송됩니다.
이 상태 코드는 403 Forbidden 상태 코드와 유사합니다. 다만 이 상태 코드가 발생하는 상황에서 사용자 인증을 통해 리소스에 대한 액세스를 허용할 수 있습니다.
https://developer.mozilla.org/ko/docs/Web/HTTP/Status/401

• 토큰이 만료 되었거나 유효하지 않을 시 다시 재인증을 요청하면 된다. 그러므로 이는 mdn에 나와있는대로 WWW-Authenticate를 응답 헤더와 함께 전송하여 다시 인증을 하도록 유도하는 401을 응답하는 것이 가장 합리적이다. 하지만 401과 굉장히 비슷하여 헷갈리는  상태코드가 있는데 403(Forbidden)이다.

HTTP 403 Forbidden 클라이언트 오류 상태 응답 코드는 서버에 요청이 전달되었지만, 권한 때문에 거절되었다는 것을 의미합니다. 이 상태는 401과 비슷하지만, 로그인 로직(틀린 비밀번호로 로그인 행위)처럼 반응하여 재인증(re-authenticating)을 하더라도 지속적으로 접속을 거절합니다.
https://developer.mozilla.org/ko/docs/Web/HTTP/Status/403

• Forbidden은 401과 비슷하지만 이는 서버에 요청이 성공적으로 전달 되었고, 인증이 되었지만 권한 때문에 거절 되었다는 것을 의미한다. 재인증을 하더라도 접속을 거절한다. 이는 ADMIN 권한이 없는 유저가 /admin 페이지를 접근하려는 것과 같은 상황에 응답해줄 상태 코드이다. 하지만 403 forbidden이 나온다는 것은 곧 해당 리소스가 존재한다는 것을 노출하고, 다른 권한이 있는 사람만 접근할 수 있다는 것을 내포하니 원치 않는 정보를 알려주는 것이나 마찬가지이다. 때문에 일괄적으로 404 Not found를 보여줘도 좋다. 이처럼 HTTP는 가끔 상황마다 다르고, 팀 내에서 정하기 나름인 부분이 있어 주의가 필요하다. 참고로 github에서 다른 사람의 private인 repository를 접근하려 하면(접근 권한이 없다면) 404 페이지가 나온다.

참고: https://mangkyu.tistory.com/146

[HTTP] HTTP 상태 401(Unauthorized) vs 403(Forbidden) 차이

서버 에러 상태 코드 500, 502, 503 차이

• 500 Internal Server Error: 서버 내부 에러. 서비스 개발자의 실수일 가능성이 매우 크게 존재한다.
• 502 Bad Gateway: 클라이언트가 리소스를 얻기 위해 게이트웨이나 프록시 서버로 요청했지만 해당 서버가 유효하지 않을 때 사용된다. 서버 측에서 요청을 보냈는데 404 Not found를 받으면 502를 띄우면 될까 싶다.
• 503 Service Unavailable: 외부 서비스가 일시적으로 이용 불가능 할 때 사용한다. 재시도 할 수 있도록 안내해준다. 404 Not found가 뜨지 않는 한 나머지 모든 외부 서비스 에러에 대해 503 에러를 띄워주면 될 것 같다.

---

HTTP Method

업데이트 PUT과 PATCH 차이

• PUT은 모든 필드를 수정할 때만 사용한다. 이는 필드를 넣지 않을 때 null이 되기 떄문에 주의가 필요하다.
• PATCH는 도메인의 부분적인 필드만 수정할 때 사용한다. 모든 필드를 수정하더라도 부분만 수정 가능한 API라면 PATCH를 사용한다. 모든 업데이트를 PATCH로 통일하는 서비스도 있는데 이 부분은 좀 더 기준을 찾아보고 정하기로 하겠다.

---

작성법

API 명은 github discussions에 영어로 정의 되어 있는 것이 아니라면 한글로 작성한다.

• 이미 나머지는 영어로 작성 되어 있으므로 빠른 파악을 위해 이름은 한글을 사용한다.(그 자체의 이름이 영어인 경우는 제외. 예시: 시험 이름, 테이블 이름)

HTTP 응답 JSON의 필드가 하나일 때도 key 값을 꼭 작성한다. JSON 형식을 항상 지킨다.

• 필드가 하나일 때는 굳이 key를 넣지 않아도 된다는 생각을 한적이 있는데 생각해보니 그렇게 되면 더이상 JSON이 되지 못한다. JSON의 정의는 key-value로 이루어져 있는 Javascript 객체 형태의 데이터이기 때문이다.
• swagger 등의 문서를 보지 않으면 필드가 하나일 때 key를 작성하지 않을 시 어떤 값인지 알 수 없어진다.
• 따로 주석을 작성하지 않더라도 알도록 한다. 

JWT를 인가 작업으로 이용하여 요청을 보낼 때 Header에 필드 명은 "Authorization", type은 기본값인 "string", 설명은 "Bearer {token}"으로 작성한다.

• 기존에는 유저를 식별 가능한 날 것의 값을 작성했는데 이를 외부 문서에 노출할 필요가 없다 판단하여 수정하였다. 실질적으로 헤더의 어떤 공간에 어떤 형식의 문자열이 담긴 토큰을 넣었는지 표시하기로 했다.

---

문법

엔드 포인트(자원, 리소스)는 도메인의 존재와 상관 없이 HTTP Method에 따라 어떤 작업을 하는지에 따라 복수형, 단수형이 나뉜다.

• 제보 API에서 사용하는 POST /contact와 같이 하나의 제보만 할 시에는 단수형을 사용해야 한다.
• 여러 개의 리소스를 다룬다면 복수형을 사용해야 한다. 전체 유저의 목록을 가져오길 바란다면 GET /users가 올바르다.
• 특정 리소스의 서브 리소스에 대한 작업은 단수를 이용한다. 예를 들어 GET /users/{userId}/preference와 같이 말이다.

HTTP Body와 JSON의 key 값은 모두 lower camel case를 사용한다.

• 프론트 개발자가 Javascript로 개발하기 용이하도록 해당 방식을 사용한다.
• 예를 들면 lowerCamelCase이다. 처음은 소문자이고, 띄어쓰기가 있을 때마다 단어의 시작을 대문자로 한다.

엔드 포인트에 띄어쓰기가 있다면 하이픈(-)을 사용한다.

• 현재 lower camel case를 대부분 사용하고 있는 조건으로써 똑같이 엔드 포인트에도 적용하면 어떨까라는 생각을 한적이 있다. 하지만 어떠한 환경에서는 대문자와 소문자를 구분하지 못하는 곳도 있다고 한다. 때문에 호환성을 생각한다면 shift를 눌러 언더 바를 사용하는 것보다 하이픈 그대로 사용하는 것의 비용이 덜 든다.
• 예를 들면 GET /test-test가 된다.