[REST API] REST API 설계

[REST API] REST API 설계

 

 기존에 만든 개인 프로젝트 URI를 수정하기 위해 사이트의 URI를 검색해보고 조사하였다. 이전에 개인 프로젝트를  진행하면서 나름 규칙이나 연결 URI를 잘 작성하였다고 생각했는데 REST API의 URI에 관해 공부를 하고 강의를 들으면서 체크를 하니 고칠 점이 눈에 들어왔다.

 

REST API

 

REpresentational State Transfer - REST API의 기본 원칙

 

1. uniform interface :  통일성 있는 인터페이스를 통해 구성 요소의 동작의 향상
   
   1. 클라이언트와 서버간의 자원을 고유하게 식별
   2. 리소스는 서버 응답에서 일정한 응답을 가져와야 함
   3. 각 리소스는 해당 리소스의 처리방식에 대한 명세가 존재해야 함
   4. 클라이언트에는 각 응용 프로그램의 초기 URI만 존재해야 함
      1. 애플리케이션은 다른 모든 리소스와 상호작용을 동적으로 구현해야 함
2. client - server
   1. client - server는 각각의 구성 요소가 독립적이어야 함
   2. 사용자 인터페이스와 서버를 분리하여 독립적으로 향상해야 함
   3. 이때 독립적으로 개발을 하여 발전해도 서로의 연결성이 끊어지면 안 된다.
3. cacheable
   1. 응답을 캐시 하여 애플리케이션은 추후 동등한 요청 / 지정된 기간 내에 해당 데이터를 재사용 가능
4. stateless
   1. 클라이언트에서 서버로 요청을 할 때 요청에 관한 정보를 모두 포함해야 함
5. layered system
   1. 레이어드의 형태로 시스템을 이룸
   2. 해당 레이어는 각자 맡은 역할만 동작할 수 있도록 제한이 된다
6. code on demand - optional
   1. 서버가 클라이언트에서 실행할 수 있는 로직을 전송하여 어떤 로직을 쓸 수 있는지 보여준다
   2. 사전에 구현해야 하는 기능의 수를 한정지어서 간소화시킨다.

• 장점
  • HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위해 별도의 인프라를 구현할 필요 X
  • HTTP 프로토콜의 표준을 활용하기에 해당 프로토콜의 장점을 가져감
  • HTTP 프로토콜이 사용이 되는 모든 플랫폼에서 사용 가능 → 범용성
  • 메시지로 의도하는 바를 명확하게 표현해야 하기에 서버는 클라이언트의 의도하는 바를 쉽게 파악 가능
  • 서비스 디자인에서 생기는 문제점 최소화
  • 클라이언트와 서비스의 역할을 분리

 

• 단점
  • 자주 변경이 되는 API
  • 너무 높은 자유도 
    • 규칙을 지키지 않아도 설계는 가능

 

 

 

URI 네이밍 규칙, 프로젝트 URI 수정

 

URI를 마음대로 정하는 것이 아닌 정해진 규칙이 존재하였다.

 

1. 동사 사용 x, 명사 사용
   1. 명사는 해당 리소스의 속성을 표현가능하지만 동사는 불가능
   2. 컨트롤 자원을 의미하는 동사의 경우 사용가능
2. 소문자 사용
   1. 소문자를 제외한 첫 글자 대문자 사용
3. 복수형 사용
4. 구분자는 "-"을 사용하기, 카멜케이스 사용 x
   1. 가독성을 위해 _ (언더바 사용 x)
5. url 마지막은 슬래쉬 포함 x
   1. "/"의 역할은 계층의 구분이기 때문에
6. 파일 확장자는 포함하지 말기
7. 컬렉션 필터링 → 쿼리 파라미터
   1. 예시 :  /users/region/ko →/users? region=ko 

 

그럼 알게 된 규칙을 바탕으로 기존에 프로젝트에서 지정한 URI를 바꿔보았다. 

기존 URI			변경 URI
/user			/users
/signup	가입	POST	/users0	POST
/login	로그인	POST	/users-login	POST
/home			/homes
/post	글 조회	GET	/posts	GET
/post	글 생성	POST	/posts	POST
/post/{id}	특정 글 조회	GET	/posts/{postId}	GET
/post/{id}	특정 글 수정	PATCH	/posts/{postId}	PATCH
/post	특정 글 삭제	DELETE	/posts	DELETE
/comment			/comments
/create/{postId}	댓글 생성	POST	/{postId}	POST
/delete/{postId}	댓글 삭제	DELETE	/{postId}	DELETE
/update/{postId}/{commentId}	댓글 수정	PUT	/{postId}/{commentId}	PUT

 

• 동사로 이루어진 API를 명사로 교체하였다.
  • 처음에는 각 버튼을 클릭 시 어떤 동작이 넘어가는지를 표시해주는 것이 좋다고 생각했기에 각 기능을 동사로 표현
  • 실제로 네이버 및 포털의 URI를 살펴보았을 때 실제로 동사로 이루어진 그런 부분은 존재하지 않음
  • login의 경우 동사인 줄 알았는데 네이버에서 login을 사용하였기에 살펴보니 명사...
• user, post, comment 등의 단수 명사를 복수 명사로 교체
  • 객체를 각각 표현한다는 의미로 단수로 표현을 하였지만 규칙에 맞게 복수로 변경하였다
• pathvariable로 가져오는 id값이 어떤 id 값이었는지 자세하게 명세하기
• create / delete / update 등의 필요 없는 동사 계층을 제거

 

참고

 

What is REST - REST API Tutorial (restfulapi.net)

What is REST - REST API Tutorial