[CS/Network] RESTFUL API

  REST  

웹에 존재하는 모든 자원(resorce, ex. 이미지, 동영상, 데이터)에 고유한 URI를 부여하여 자원에 대한 주소를 지정하는 방법론, 또는 규칙.

 REST 특징 

• 인터페이스 일관성 : 일관적인 인터페이스로 분리되어야 한다
• 무상태(Stateless): 각 요청 간 클라이언트의 콘텍스트가 서버에 저장되어서는 안 된다
  1. HTTP 프로토콜은 Stateless Protocol이므로 REST 역시 무상태성을 갖는다.
  2. Client의 context를 Server에 저장하지 않는다.
  3. Server는 각각의 요청을 완전히 별개의 것으로 인식,  처리한다.
     
  4. Server의 처리 방식에 일관성을 부여하고 부담이 줄어들며, 서비스의 자유도가 높아진다.
• 캐시 처리 가능(Cacheable): 웹 표준 HTTP 프로토콜을 그대로 사용하므로 웹인프라를 그대로 활용할수 있다.
  • WWW에서와 같이 클라이언트는 응답을 캐싱할 수 있어야 한다.
  • 잘 관리되는 캐싱은 클라이언트-서버 간 상호작용을 부분적으로 또는 완전하게 제거하여 scalability와 성능을 향상시킨다.
• 계층화(Layered System): 클라이언트는 보통 대상 서버에 직접 연결되었는지, 또는 중간 서버를 통해 연결되었는지를 알 수 없다. 중간 서버는 로드밸런싱 기능이나 공유캐시 기능을 제공함으로써 시스템 규모 확장성을 향상시키는 데 유용하다.
• Code on demand (optional) - 자바 애플릿이나 자바스크립트의 제공을 통해 서버가 클라이언트가 실행시킬 수 있는 로직을 전송하여 기능을 확장시킬 수 있다.
• 클라이언트/서버 구조 : 아키텍처를 단순화시키고 작은 단위로 분리(decouple)함으로써 클라이언트-서버의 각 파트가 독립적으로 개선될 수 있도록 해준다..

 RESTful  

REST 특징을 지키면서 API를 제공한다는 의미다.  명시성있는 url 작명

REST 규칙

• url 은 page 기준이 아닌 resource 기준으로 작성
• 여러 종류의 정보를 표출해야 한다면, 협의하여 REST에 맞춰 두가지 이상의 endpoint를 동시 호출
• 동사사용금지 URI는 명사를 사용
• 컨트롤 자원을 의미하는 URL은 예외적으로 동사를 허용해도 된다.
• 슬래시로 계층 관계를 표현한다.
• URI의 마지막에는 슬래시를 붙이지 않는다.
• URI는 소문자로만 구성
• 가독성이 떨어지는 경우 (underbar) 대신 -(dash)를 사용한다.

 

Query Parameters VS Path Parameters

1. Query parameters (GET parameters)

url 주소를 자세히 보면 종종 ?가 포함되어 물음표 뒤에는 늘 key=value 형식의 문자열이 따라옵니다.
이를 Query parameter 라고 부른다. 데이터를 조건으로 거르거나(filtering), 특정 방식으로 정렬하거나(sorting), 검색(searching)하고자 하는 경우에 활용한다.

/users # 사용자 목록 가져오기 
/users?occupation=programer # 프로그래머 목록 가져오기 user 
/users/123 # ID가 123인 사용자 가져오기

 

2. Path parameters

리소스에 더 자세한 정보를 얻기 위해 접근할 때 사용합니다.

 

정리하자면 만약 어떤 resource를 식별하고 싶으면 Path Variable을 사용하고,
정렬이나 필터링을 한다면 Query Parameter를 사용하는 것이 가장 좋다.