REST에 대해 공부하던 중 문득 그런 생각이 들었다.
REST하게 설계하고 만드는 것이 좋은 REST.API인가?
규칙대로 지키는 것이 좋은 방식인가?
이러한 의문점들이 들었다.
좋은 REST.API가 무엇인지 알아보기전에 REST가 뭐고 API가 뭐고 REST.API가 뭔지 짚고 넘어가보자.
REST란?
1.
REST의 정의
Representational State Transfer의 약자
•
자원을 이름으로 구분하여 해당 자원의 상태 및 정보를 주고 받는 아키텍처 스타일
◦
아키텍처란? : 구성요소들 사이에서 유기적 관계를 표현하고 설계와 업데이트를 통제하는 지침과 원칙
2.
REST의 구체적인 개념
HTTP URI를 통해 자원을 명시하고 HTTP Method를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다.
•
REST는 설계의 중심의 리소스가 있고 HTTP Method를 통해 리소스를 처리하도록 설계된 아키텍처를 의미한다
•
웹 사이트의 이미지, 텍스트, DB 내용 등의 모든 자원에 ID인 HTTP URI를 부여한다.
API란?
1.
API의 정의
Application Programming Interface의 약자
•
응용프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스
•
한 프로그램에서 다른 프로그램으로 데이터를 보내주기 위한 방법
2.
API의 종류
a.
private : API를 내부에서만 사용할 수 있도록 한다.
b.
partner : API를 특정 파트너와 공유한다.
c.
public : API가 모두에게 제공된다.
REST.API란?
1.
REST.API의 정의
REST 기반으로 서비스 API를 구현한 것을 말한다.
2.
REST.API의 설계 규칙
a.
소문자 사용
•
URI는 대문자가 아닌 소문자로 설계한다.
b.
언더바(_)대신 하이픈(-)사용
•
긴 명사는 하이픈을 이용해 구분한다.
c.
URI의 마지막에는 슬래시를 포함하지 않는다.
•
의미가 없으므로 포함하지 않는다.
d.
계층 관계를 나타낼 때는 슬래시 구분자 사용한다.
e.
파일 확장자는 URI에 포함시키지 않는다.
•
파일 확장자는 요청 시 헤더의 Content-Type 속성을 변경할 수 있다.
f.
대부분의 경우 이용하는 자원의 명사를 사용하지만, 컨트롤 자원을 의미하는 경우 동사를 허용한다..
g.
자원의 명사는 복수형으로 작성
h.
URI에 Method를 포함하지 않는다.
3.
응답상태코드
•
1XX : 전송 프로토콜에서의 정보교환
•
2XX : 클라이언트 요청 성공
•
3XX : 클라이언트 측 추가적인 정보 필요
•
4XX : 클라이언트 측 잘못된 요청
•
5XX : 서버 측 오류
++ RESTful
•
RESTful 하다는 것은 적절한 REST API를 제공한다는 뜻이다. 즉 위에 원리들을 모두 따른다는 의미를 가진다.
개념들을 알아봤는데 REST.API는 정해진 규칙들을 토대로 API를 구현,설계하는 것을 말한다고 한다. 그리고 추가적으로 RESTful의 개념도 알아봤는데 REST하게 설계하고 구현한 API가 과연 좋은 것인지? 하는 의문이 들었다. 정답은 없는 의문인 것 같지만 한번 궁금증을 조금이라도 해소해보도록 해보자.
기초적이고 간단한 REST.API를 설계해보자
시나리오 : 회원 정보 관리 API
[API 설계 리스트]
•
회원 등록
•
회원 조회
•
회원 목록 조회
•
회원 수정
•
회원 삭제
[API URI 설계 예시 - 1]
•
회원 등록 : /create-user
•
회원 조회 : /read-user-id
•
회원 목록 조회 : /read-user-list
•
회원 수정 : /update-user
•
회원 삭제 : /delete-user
[API URI 설계 예시 -2]
•
회원 등록 : /users/{id}
•
회원 조회 : /users/{id}
•
회원 목록 조회 : /users
•
회원 수정 : /users/{id}
•
회원 삭제 : /users/{id}
예시 1은 좋은 방식일까? 회원이라는 리소스가 식별이 어렵다고 느껴진다 .
예시 2는 RESTful 원칙을 따라 만들었다. 모든 경로가 /users 로 시작하여 일관된 리소스 접근 방식을 제공한다 그렇다면 예시 2는 어떻게 구분할까?
바로 Method,행위을 통해 나눌 수 있다.
리소스는 회원, 행위는 Method(GET,POST 등)로 분류할 수 있는 것이다.
예시 2는 일관성있는 URI를 사용함과 동시에 리소스 식별이 쉽다고 느껴진다 심지어 URI에 최소화한 정보들만 넣었으므로 정보 보안 측면에서도 예시 1보단 좋다고 볼 수 있다.
예시를 직접 들어보니 좋은 API는 리소스 식별이 중요하다고 느낀다. 예시 1이 틀린 API설계는 아니지만 상대적으론 안좋다라고 느꼈고 정보 보안 측면에서도 예시 1보단 예시 2가 우수하다고 느꼈다. 그래서 REST가 왜 표준이 됐는지도 이해를 하였다.
물론 항상 실무에서는 전부 RESTful하게 만들 수는 없을 것이다. 그래도 표준이 된 REST 규칙을 지키는게 좋은 API설계라고 느꼈다.