Rest API란?

API

---

클라이언트와 서버는 서로 직접적으로 호출하기보다는, Application Programming Interface (API)라 불리는 중간자 역할의 인터페이스를 사용합니다.

 

REST

---

정의

Representational State Transfer의 약자로 해석하면 원하는 리소스를 현재 상태에 걸맞은 형태로 전송하는 것이다. 즉 자원의 표현에 의한 상태 전달을 뜻합니다.

• 자원: 해당 소프트웨어가 관리하는 모든 것 (문서, 그림, 데이터 등)
• 표현: 그 자원을 표현하기 위한 이름 (DB의 학생 정보가 자원이면, 'students'를 자원의 표현으로 정한다.)
• 상태 전달: 데이터가 요청되는 시점에 자원의 상태를 전달한다. (JSON, XML 등)

REST는 웹의 기존 기술과 HTTP 프로토콜을 그대로 사용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일입니다.

 

개념

어떤 자원에 대해 CRUD 연산을 수행하기 위해 URI(Resource)로 Get, Post 등의 방식을 사용하여 보내며, 요청을 위한 자원은 특정한 형태로 표현됩니다.

URL - 인터넷상 자원의 위치를 의미합니다.
URI - 인터넷 상의 자원을 식별하기 위한 문자열의 구성으로 URI는 URL을 포함하여 더 포괄적인 범위입니다.

특징

Client - Server (서버 - 클라이언트 구조)

• API를 통해 정보를 교환하는 주체는, 클라이언트와 서버 구조를 가져야 합니다.
• 클라이언트와 서버의 역할을 확실히 분리하여 서로 의존하지 않는 구조를 가져야 합니다.

Stateless (무상태)

• HTTP 프로토콜은 Stateless Protocol이므로 REST 역시 무상태성을 갖습니다.
• Client의 context를 Server에 저장하지 않습니다.
  • 세션과 쿠키와 같은 context 정보를 신경 쓰지 않아도 되므로 구현이 단순해집니다.
• Server는 각각의 요청을 완전히 별개의 것으로 인식하고 처리합니다.
  • 이전 요청이 다음 요청의 처리에 연관되어서는 안 됩니다.

Cache (캐시)

• 요청에 대한 응답 내의 데이터에 캐시 가능여부가 명시되어 있어야 합니다.
• cache-control 헤더를 통해 명시 가능합니다.

Laryered System (계층 구조)

• 클라이언트는 서버에 직접 연결되었는지, 중간 서버를 통해 연결되었는지 알 수 없어야 합니다.
• REST Server는 다중 계층으로 구성될 수 있습니다.
  • Proxy, Gateway와 같은 네트워크 기반의 중간매체를 사용할 수 있습니다.

Code-On-Demand (Optional)

• Server에서 보낸 코드를 Client에서 실행할 수 있어야 함을 의미합니다.
• 필요에 따라, 지켜도 되고, 지키지 않아도 REST에는 문제가 없습니다.

Uniform Interface (인터페이스 일관성)

• 전체적인 시스템 아키텍처를 간단하고 잘 파악할 수 있도록 약속된 인터페이스를 제공해야 합니다.

Uniform Interface의 특징

1. 자원에 대한 식별 - dentification of resources

 

요구사항	잘못된 예시	rest를 지킨 예시
회원 목록 조회	/read-member-list	/members
회원 조회	/read-member-by-id	/members/{id}
회원 등록	/create-member	/members
회원 수정	/update-member	/members{id}
회원 삭제	/delete-member	/members{id}

 

회원을 조회, 등록, 수정, 삭제 명령이 자원을 의미하지도 않으며, 식별할 수 있는 식별자 값도 아닙니다.

따라서 URI에 제어하고자 하는 자원에 대해 명시하고, 그 객체를 식별할 수 있는 변하지 않는 식별자{id}를 URI를 통해 식별할 수 있도록 해야 합니다.

 

2. 표현을 통한 자원에 대한 조작 - Manipulation of resources through representations

• HTTP 메서드(표현)를 통해 HTTP 메시지에 해당 리소스에 대해 어떤 조작을 하는지 명시해야 합니다.

3. 자기 서술적 메시지 - Self-descriptive messages

• 메시지를 읽는 모든 주체들이, 메시지의 모든 요소는 메시지만 보고 그 의미를 파악할 수 있어야 합니다.

4. HATEOAS - Hypermedia as the engine of application state

• 하이퍼 미디어를 통한 앱 상태 변경 인터페이스를 제공해야 합니다.(현재 상태에서 어떤 페이지로 이동가능한지 보여야 합니다.)

 

REST API

---

정의

REST의 특징을 기반으로 서비스 API를 구현한 것을 말합니다.

 

특징

각 요청이 어떤 동작이나 정보를 위한 것인지를 그 요청의 모습 자체로 추론이 가능합니다.

 

설계 가이드

가장 주 용한 항목은 2가지가 있습니다.

1. 리소스에 대한 행위는 HTTP Method(POST, GET, PUT, DELETE)로 표현해야 합니다.

2. URI는 정보의 자원을 표현해야 합니다.(행위는 URI에 포함되지 않습니다.)

 

설계 규칙

1. URI는 복수 명사를 사용합니다.(리소스명은 동사가 아닌 명사)
   
   1. https://mysite.com/post/123 같은 엔드포인트가 있다면, POST 요청으로 게시물을 생성하거나, PUT, PATCH 요청을 통해 갱신하는 게 가능합니다. 그러나 사용자는 다른 게시물들이 있음을 알아채기 힘들 수 있어 복수 명사를 사용합니다. 따라서 https://mysite.com/posts/123와 같은 엔드포인트가 되어야 합니다.
   2. /getAllUser, /getUserById 등 동사는 사용하지 않습니다.
2. 슬래시(/)로 계층 관계를 표현합니다.
   1. 블로그 플랫폼의 경우 여러 게시물이 각기 다른 사용자들에 의해 작성됩니다.
      1. 엔드포인트는 http://mysite.com/posts/author와 같이 사용합니다.
   2. 게시물들은 각자 댓글들을 가지고 있기에 댓글을 조회할 수 있습니다.
      1. 엔드 포인트는 https://mysite.com/posts/postId/comments와 같이 사용한다.
   3. 3단계 이상 중첩하면 가독성이 떨어지기 때문에 너무 많이 중첩하지 않는 것이 좋습니다.
3.  HTTP 응답 상태 코드를 사용합니다.
   1. API 요청에 대해 응답할 때는 항상 HTTP 상태 코드를 포함해야 합니다.
      그래야 사용자가 요청이 성공했는지, 실패했는지 상태를 확인할 수 있기 때문입니다.
4. 데이터를 받을 때 필터링, 정렬, 페이지네이션을 사용합니다.
   1. API의 데이터베이스의 규모가 큰 경우에는 데이터베이스에서 데이터를 받아올 때 느려질 수가 있습니다. 필터링, 정렬, 페이지네이션을 통해 필요한 데이터만 걸러내어 요청에 대한 부담을 줄일 수 있습니다. 필터링된 엔드포인트를 보면 https://mysite.com/posts?tags=javascript와 같이 사용할 수 있습니다.
5. URI 마지막 문자로 /를 사용하지 않는다.
6. 밑줄( _ ) 대신 하이픈( - )을 사용한다.
7. 영어 대문자보다는 소문자를 사용한다.
8.  파일확장자는 URI에 포함하지 않습니다.

 

정리

---

• 클라이언트와 서버의 요청 및 응답을 위해 API를 사용한다.
• API를 설계할 때 REST 아키텍처를 사용하여 정해진 규격에 맞게 설계한다.
• REST API 설계 시 주의점
  • URI는 복수 명사를 사용합니다.
  • 슬래시(/)로 계층 관계를 표현합니다.
  • HTTP 응답 상태 코드를 사용합니다.
  • 데이터를 받을 때 필터링, 정렬, 페이지네이션을 사용합니다.
  • URI 마지막 문자로 /를 사용하지 않는다.
  • 밑줄( _ ) 대신 하이픈( - )을 사용한다.
  • 영어 대문자보다는 소문자를 사용한다.
  • 파일확장자는 URI에 포함하지 않습니다.