RESTful API

이 글은 Computer Science에 관한 앎의 지평을 넓히기 위해

초보자를 위한 면접 질문 깃허브를 보며 공부한 내용을 정리한 것입니다.

---

1. API란?

Application Programming Interface

a set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service. (Oxford Languages)

응용 프로그램에서 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스 (위키백과)

흔히 사용되는 모습을 서술하자면, 응용 프로그램에서 데이터를 주고 받는 방법이라고 할 수 있을 것이다.

API 문서에는 어떤 정보에 접근할 수 있는지와, 해당 정보를 요청하는 방식이 함께 기술되어 있기 때문이다.

 

2. REST란?

REST란 Representational State Transfer의 약자로, 로이 필딩(Roy Fielding)의 2000년 논문에서 처음 언급된 용어이다. 자원을 정의하고 자원의 주소를 지정하는 방법 전반에 관한 패턴을 의미한다. 간단히 말하자면, HTTP를 십분!!! 활용하자는 소프트웨어 아키텍처이다. (HTTP 메서드 웨않써)

REST의 골자는 자원과 행위를 분리하는 것이다. (용어 자체가 자원을 이름(자원의 표현)으로 구분하여 해당 자원의 상태를 주고 받는 것을 의미한다.) 

REST는 다음과 같이 구성된다:

자원: URI
행위: HTTP Method (GET, POST, PUT, PATCH, DELETE)
표현: JSON, XML 등

정보는 URI로, 행위는 HTTP Method로 분리한다!

 

3. REST의 특징

1) Uniform Interface

 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다.

2) Stateless (무상태성)

세션이나 쿠키 등의 상태 정보를 저장하지 않고, API로 들어오는 요청만 처리한다. 이는 구현을 단순하게 해준다.

3) Cacheable

HTTP의 이점을 활용하므로 캐시 저장 기능도 사용할 수 있다. HTTP 프로토콜 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용하면 된다.

4) Self-descriptiveness (자체 표현 구조)

생김새가 의미를 내포한다. 즉, REST API 메시지만 보고도 그 목적을 알 수 있게 하는 것이다.

5) Client - Server 구조

REST 서버는 API를 제공하고, 클라이언트는 사용자 인증이나 세션 등을 직접 관리하는 식으로 역할이 명확하게 구분되며 상호간 의존성이 줄게 된다.

6) Hierarchical system

REST 서버는 다중 계층으로 구성하여 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고, PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 해준다.

 

4. REST의 장단점

장점

1. Open API 를 제공하기 쉽다.
2. 멀티플랫폼 지원이 용이하다.
3. 원하는 타입으로 데이터를 주고 받을 수 있다.
4. 기존 웹 인프라(HTTP)를 그대로 사용할 수 있다.

단점

1. 사용할 수 있는 메소드가 한정적이다.
2. 분산환경에는 적합하지 않다.
3. HTTP 통신 모델에 대해서만 지원한다.

 

5. RESTful API 잘 작성하는 방법

1) 일관되게 작성하기

API를 보면 어떤 일을 수행하는지 예측가능하도록 작성하는 것이 중요하다.

• 케이스 통일하기: 주로 snake_case를 사용하되, 밑줄(_)은 잘 보이지 않으므로 하이픈(-)으로 대체한다.
• 엔드 슬래시(/)를 사용하지 않는다. (불필요한 요소를 추가하지 않는다)
• 컬렉션은 복수형, 도큐먼트는 단수형 (※ 도큐먼트의 집합이 컬렉션이라고 생각하면 됨)
  
  • 예) subjects — math

2) ISO 8601 UTC 날짜 포맷을 사용하자.

3) public endpoint는 인증 예외 처리하기

기본값으로 인증을 포함시켜야 한다. 인증 없이 요청되어야 하는 public endpoint는 예외로 명시한다.

4) Health-check endpoint 만들기

서비스 정상 작동여부를 확인할 수 있는 엔드포인트를 하나 만들어두자.

5) API 버전화 하기

6) API 키 인증 적용하기

HTTP 헤더를 통해 api key를 받아 인증이 처리될 수 있도록 한다.

7) HTTP 상태코드를 잘 활용하자

같은 결과에 대해선 같은 상태코드를 적용하는 등 일관적으로 사용하고, 가짓수를 한정하여 너무 다양하게 사용하지는 않도록 한다.

HTTP 상태 코드는 여기 참조. 

8) HTTP 메서드를 잘 사용하자

GET - Read
POST - Create
PUT / PATCH - Update
DELETE - Delete

❓ PUT과 PATCH의 차이점

PUT은 전체 정보를 대체하는 것이고, PATCH는 일부분을 변경할 때 사용한다.

일부 항목만 바꾸더라도 PUT을 사용하면 변경하지 않은 항목들까지 전체를 넘겨주어야 한다.

 

9) 이름은 간단하게, 명시적으로

10) 표준 에러 응답 사용하기

일관성 있는 에러 코드를 응답하고, 메시지에는 에러의 구체적인 정보를 적어준다.

11) POST 사용 시, 객체를 반환하기

POST 메서드로 객체를 생성했을 때에는 만들어진 객체를 응답에 포함하여 상태 정보를 확인할 수 있도록 한다.

12) PUT 보다는 PATCH 사용하기

전체 정보를 갱신할 일은 많지 않으며, 불필요한 정보까지 전달하게 된다면 데이터의 무결성을 해칠 위험이 있다.

13) 최대한 구체적으로

엔드포인트, 필드명 등 전반에서 구체적으로 명명할수록 좋다.

14) 페이지네이션 사용하기

사용자가 요청하는 페이지 넘버와 페이지 사이즈를 응답에도 함께 실어 보내준다.

15) 자원을 확장 가능하게 하기

expand 등의 쿼리 파라미터를 통해 사용자가 연관성 있는 추가 정보도 리턴 가능하게 설계한다.

 

---

참고

• REST API 제대로 알고 사용하기
• How to design better APIs
• REST 아키텍처를 훌륭하게 적용하기 위한 몇 가지 디자인 팁