(REST API) 사용/개발 조건

• URI, HTTP METHOD, 표현으로 구성
• URI는 정보의 자원을 표현
• 리소스 행위는 HTTP METHOD로 표현
• 하나의 API에는 다른 성질의 데이터를 담지 않기
• 소문자로 작성, '-' 사용하고, 반대로 대문자를 사용하지 않고, '_'를 사용하지 않음
• 응답 상태코드는 200, 201, 401, 401, 403, 404, 405, 406, 500 정도만 알아도 문제 없음
• JAVA는 ResponseEntity 적극 활용(응답 코드, 헤더, 본문 모두 다루기 편리함)
  • 간혹 협업하다보면 Map 자체를 리턴하는 개발자가 있는데 비추천

 

•  URI 작성 요령

   GET /members/show/1   (X)    GET /members/1     (O)

   GET /members/insert/2 (X)    POST /members/2    (O)

 

• 파일의 확장자는 포함시키지 않고, Accept header로 받을 데이터 타입을 정의함

GET /members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

 

• Self-descriptive message를 만족하는가
  • 메시지 스스로 메시지에 대한 설명이 가능해야함
  • 서버가 변해서 메시지가 변해도 클라이언트는 메시지만 보고 해석 가능해야함

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://korea.com/docs/subway>; rel="profile"
{
   "id":1,
   "name":"선릉역"
}

 

• HATEOAS
  • 해당 API의 정보를 담은 링크를 제공함
  • 해당 API의 응답값을 토대로 진행할 수 있는 작업에 대한 API를 제공함
  • 클라이언트의 로그인 여부 및 권한 여부에 따라 유동적으로 링크를 제공함

HTTP/1.1 200 OK
Content-Type: application/json
Link:</subways/1/times>; rel="times",
      </subways/1/detail>; rel="detail"
{   
   "id":1,
   "name":"선릉역"
}

 

Self-descriptive message와 HATEOAS를 만족할 경우, 응답값을 한눈에 알아보기 쉽고, URI 변경이 이루어져도 클라이언트는 응답값 안의 URI만 호출하면 되기 때문에 영향이 없다.