Web API란

REST API의 모든 스타일을 구현하지 못할 경우에는 Web API나 HTTP API라고 부른다.

Web API 디자인 가이드

  • URI는 정보의 자원을 표현해야한다.
  • 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

HTTP Method

METHOD 역할
POST POST를 통해 해당 URI를 요청하면 리소스를 생성한다.
GET GET를 통해 해당 리소스를 조회한다. 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다.
PUT PUT를 통해 해당 리소스를 수정한다.
DELETE DELETE를 통해 리소스를 삭제한다.

URI는 정보의 자원을 표현해야 한다.

조회, 입력, 삭제, 수정과 관련된 것들이 동사로 표현되면 안된다.

  • GET /members : 위의 표현은 맴버의 모든 정보를 달라는 요청입니다.
  • GET /members/delete/1 (x): GET은 정보를 요청할 때 사용합니다. 위와 같이 동사로 삭제를 표현하면 안 됩니다.
  • DELETE /members/1 : HTTP Method 중의 하나인 DELETE를 이용하여 삭제를 표현해야 합니다.

자원에 대한 행위는 HTTP Method로 표현

  • GET /members/1 (o)
  • GET /members/get/1 (x)
  • GET /members/add (x)
  • POST /members (o)
  • GET /members/update/1 (x)
  • PUT /members/1 (o)
  • GET /members/del/1 (x)
  • DELETE /members/1 (o)

슬래시 구분자(/)는 계층을 나타낼 때 사용

  • http://domain/houses/apartments : 집들 중에서 아파트들만 주세요.
  • http://domain/departments/1/employees : 모든 부서들 중에서 1번 부서의 사원
  • URI 마지막 문자로 슬래시 구분자(/)를 포함하지 않습니다.
  • 하이픈(-)은 URI가독성을 높일 때 사용합니다.
  • 언더바(_)는 사용하지 않습니다.
  • URI경로는 소문자만 사용합니다.
  • RFC 3986(URI 문법 형식)은 URI스키마와 호스트를 제외하고는 - 대소문자를 구별합니다.
  • 파일 확장자는 URI에 포함하지 않습니다.
  • Accept Header를 사용합니다.

상태코드

성공

클라이언트로 인한 오류

  • 403번 보다는 400번이나 404번으로 응답할 것을 권고
    • 응답하고 싶지 않은 리소스를 클라이언트가 요청했는데 403번이라고 보내면 이미 이 리소스는 존재한다는 것을 알려주기 떄문에

서버로 인한 오류

  • 500번대 상태코드는 대부분 서버가 잘못했을 때 나오는 것들
    • 중간에 서버가 프로그램 돌다가 NullPointerException이 발생됐다.

참고