개요

필자가 서버개발을 하다 필요한 REST API 표준 규격을 정의한다.

정의방식

찾아본 바로는 REST API의 표준 규약은 따로 정의되어있지 않고 표준에 가까운 시도들만 여러 자료가 존재한다. 따라서 KAP 개발에 맞춰 일관성을 가지며 실용적인 수준에서 API 규격을 정의한다.

URL 규칙

• 소문자를 사용한다.
• URL 마지막에 /를 포함하지 않는다.
• 필요에 따라 -을 사용해도 된다.
• 리소스 명은 명사만으로 구성한다.
• 행위(method)는 URL에 포함하지 않는다.
• PUT/POST 와 insert update의 상관관계
• 기본 URL 및 method 예시
  • /bookmarks
  • GET : 즐겨찾기 목록
  • POST : insert(즐겨찾기 추가)
  • / bookmarks/{bookmark-id}
  • GET : 즐겨찾기 1 row 조회
  • PUT : insert/update(즐겨찾기 추가/수정)
  • DELETE : 즐겨찾기 삭제

Request Header 규칙

• Content-Type은 application/json으로 통일

Request Parameter 규칙

• GET 메소드 사용시
  • 필요 파라미터는 항상 쿼리스트링으로 기재한다.
  • 예를들면 ldap_id, page_no, page_size등이 여기에 해당할 수 있다.
• POST 메소드 사용시
  • 필요 파라미터는 항상 form data로 기재한다.
  • 예를 들면 ldap_id, menu_id 등이 여기에 해당 할 수 있다.

Response Header 규칙

• 신경쓰지 않아도 자동 입력된다.
• Content-Type은 application/json으로 통일
• “access-control-allow-origin”: “*” 으로 CORS를 해결

Response 규칙

• API 정상/비정상 여부는 의미에 맞는 HTTP status code를 리턴하여 표시
  • 200 : 정상
  • 400 : Request validation 실패(int값 자리에 string이 들어오는 경우 등)
  • 401 : 권한 오류(로그인 실패 및 권한 오류)
  • 404 : Resource가 없는경우
  • 422 : Unprocessable Entity(DB insert 실패 등)
  • 이외에 필요시 jack에게 문의하거나 본인이 찾아서 추가
• 기본 response 규격은 {"msg": "에러메세지 노출 필요시 기입", "results": [필요한object]}로 정의한다.
  • 성공시 예제
    {"msg": "", "results": [필요한object]}
  • 실패시 예제
    {"msg": "invalid request", "results": null}