🌿 RestFul 설계를 지키는 API, 그렇지 않은 API

공부 계기

Rest Ful한 설계 라는 표현을 정말 많이 들어봤지만 명확하게 설명할 수 없었다.
정확히 모른 채로 API를 만들다보니 결과물로 받은 API 문서가 엉망이었다.
이번 글을 통해 개념을 정립하고 내가 설계한 API를 수정해보면 좋을 것 같다.

현재 API 문서

제목	메서드	URL
특정 제품의 옵션 목록 조회	GET	/api/options/{product_id}
새로운 옵션 추가	POST	/api/options/{product_id}
옵션 삭제	DELETE	/api/options/{option_id}

---

API란?

API는 Application Programming Interface, 즉 어플리케이션 프로그래밍 인터페이스다.
인터페이스는 어떤 장치와 장치를 연결해주는 장치를 말한다.
따라서 API는 어플리케이션 프로그램끼리 통신할 수 있도록 하는 장치,아키텍처이다.

그러면 함수도 인터페이스인가요?

🙅‍♂️ 함수는 프로그램 내부에서 사용하는 코드이다.
일반적으로 API를 이야기 할때는 외부의 다른 프로그램이나 모듈이 사용하는 인터페이스를 말한다.

API는 웹 API만 있는 것은 아니다.

API는 어플리케이션끼리 통신하도록 하는 것이다. 따라서 웹이 아닌 API도 존재한다.

• 프레임워크 API : 스프링과 같은 프레임워크의 라이브러리도 API의 일종이다.
• 멀티미디어 API : 멀티미디어를 처리하기 위한 멀티미디어 API도 존재한다.

---

웹 API

웹을 통해 클라이언트와 서버간의 통신을 할 수 있게 하는 API이다.

웹 API는 모두 HTTP API일까?

🙅‍♂️ 네트워크 쪽 개념이지만, 다양한 통신 방법이 존재한다.
양방향 통신을 할 수 있는 WebSocket은 초기연결에만 http를 사용한 후 연결을 끊지 않는다.

HTTP란
주로 웹 환경에서 클라이언트와 서버간의 통신을 관리하는 데 사용하는 네트워크 프로토콜이다.

HTTP API는 모두 REST API일까?

HTTP API는 HTTP 프로토콜을 사용해서 데이터를 교환하는 API를 의미한다.
또 Rest API는 REST 아키텍처를 따르는 API를 말한다. 따라서 동의어는 아니지만 거의 REST 아키텍처를 따르도록 API를 설계하기 때문에 비슷한 의미로 쓰이는 중이다.

---

REST API

REST API를 설명하기 위해서 HTTP API > 웹 API > API 까지 알아보았다. 다시 REST API 내용으로 돌아오자! ✈️

REST API란?

REST 아키텍처란 HTTP 프로토콜의 장점을 활용할 수 있게 하는 일종의 설계방법,지침서이다.

REST API란,이런 REST 지침서를 잘 지키킨 API라고 할 수 있다.

또한 REST FUL하다는 표현은 REST의 설계도를 잘 지켰다는 것을 의미한다.

REST하기 위해서는

1) 일관적인 인터페이스

2) 무상태 : 클라이언트의 이전 요청 상상태를 저장하지 않는다. 서버는 들어오는 요청에만 응답하고 처리한다. 이를 통해서 구현이 단순해지고 자유도가 높아진다.

3) 캐시 처리 가능 : 클라이언트나 중간 캐시서버에 저장된 응답 데이터를 재사용하여 서버가 반복수행을 하는 것을 막아준다.

4) 계층화 : REST 서버는 다중 계층으로 구성될 수 있다.

5) 자체로 이해가능해야한다. : 적절한 URI 설계와 http 메서드의 활용을 통해서 이룰 수 있다.

6) 클라이언트 - 서버 구조 : 클라이언트와 서버의 역할을 명확하게 구분할 수 잇다.

이건 불충분하니 REST API를 설계하기 위한 규칙과 예제를 이야기하겠다.
그 전에 아래 두가지 규칙은 필수로 지켜야하는 규칙이라고 한다.

---

REST API 설계 규칙

(1) URI로 정보의 자원을 표현해야한다.

URI에는 CRUD와 같은 자원에 대한 행위를 담지 않고, 자원을 나타내는 수단으로만 사용한다.

또한 URI의 자원은 객체보다는 엔티티를 뜻한다. 조금 더 집합의 개념으로 쓰이기 때문에단수형보다는 복수형으로 나타낸다.

(2) 자원에 대한 행위는 HTTP 메소드로 표현한다.

HTTP 메서드는 GET, POST, PUT, DELETE , PATCH 등이 있다.
URI로 표현한 자원에 대한 행위는 HTTP 메서드를 사용해서 표현하는 것이다.

 GET /members/1 : -> 1번 유저의 정보를 가져온다.
 DELETE /members/1 : -> 1번 유저의 정보를 삭제한다.

위처럼 행위설명은 HTTP 메서드를 사용하는 것이다.

적절한 자원 표현법을 알아보자.

복수명(컬렉션)을 사용하자.

URI에서 자원은 복수로 표현되고, 단일 자원(document) 에 접근할 때는 자원 컬렉션에 고유 식별자를 추가해서 표현한다.

/users : 사용자 컬렉션
/users/1 : 식별자가 1인 단일 사용자

/sports/soccer 
/sports/soccer/players/13 

URI에서 자원을 표현할 때는 실제 자원의 관계를 고려한다.

(ex) GET /cars/811/drivers/ 		> 차811 의 드라이버 리스트를 반환한다.
(ex) GET /cars/811/drivers/4		> 차 811의 4번 드라이버 정보를 반환.

* 계층 관계를 나타낼 때 슬래시(`/`)를 사용할 수 있다. 

쿼리 파라미터는 특정 조건을 표현하는데 사용된다.

쿼리 파라미터로 검색의 조건, 페이지네이션, 정렬기준 등등을 표현할 수 있다.

GET /users?fields=id,name,email : 사용자 목록에서 id, name, email 필드만 반환

더 상세한 REST API 규칙을 알아보자.

• 에러는 HTTP의 상태코드와 메시지를 사용해서 처리한다.
• 버전을 명시할 수도 있다.
• URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
• 밑줄을 사용하지 않고 하이픈을 사용한다.
• 대문자가 아닌 소문자를 생각한다.
• 파일 확장자는 URI에 포함하지 않는다.

---

리팩토링하기

REST Ful한 설계에서 본 내 API의 문제점

아래 API 문서는 어떤 문제점이 있을까?? 🤔

제목	메서드	URL
특정 제품의 옵션 목록 조회	GET	/api/options/{product_id}
새로운 옵션 추가	POST	/api/options/{product_id}
옵션 삭제	DELETE	/api/options/{option_id}

• 계층형 구조를 고려한다면 포함되는 컬렉션이 뒤에 온다.
  products > options 순서가 더 적절할 것이다.

• 컬렉션 뒤에 오는 값은 그 컬렉션의 도큐먼트를 나타낸다.
  options뒤에 오는 식별자 값은 {option_id}이 적절할 것이다.

• 통일성을 지키지 못했다는 문제점도 있다.

적절하게 바꾼 API

제목	메서드	URL
특정 제품의 옵션 목록 조회	GET	/api/products/{product_id}/options
새로운 옵션 추가	POST	`/api/products/{product_id}/options
옵션 삭제	DELETE	/api/products/{product_id}/options/{option_id}

통일성을 가지게 되었고 컬렉션>도큐먼트의 규칙과 적절한 계층 구조를 가지게 되었다 👍👍

---

하지만 이런 REST API를 늘 지킬 수 있는 것은 아니다.

내 상황

• 내 서버에서 카카오 API를 사용하기 위해 사용자별 토큰을 사용해야했다.
  REST API를 위해서는 무상태를 위해 서버가 클라이언트의 상태나 정보를 저장하지 않도록 하지만 보안 상 이 토큰은 주고받지 않고 서버 내부에서만 사용해야한다.

위 경우에는 보안을 위해서 무상태성을 깨는 것이 더 적절할 것이다. 이처럼 모든 REST API를 엄격하게 지키는 것이 아니라 실무 운영 별로 적절한 도입을 고려해야한다.

---

참고자료

AWS RestFul API
https://meetup.nhncloud.com/posts/92
https://jins-dev.tistory.com/entry/Rest-API-%EC%84%A4%EA%B3%84%EB%A5%BC-%EC%9C%84%ED%95%B4-%EA%B0%9C%EB%B0%9C%EC%9E%90%EA%B0%80-%EC%95%8C%EC%95%84%EC%95%BC%ED%95%A0-10%EA%B0%80%EC%A7%80-%EC%B2%B4%ED%81%AC-%EB%A6%AC%EC%8A%A4%ED%8A%B8