REST API URL 규칙

RESTful API란?

REST(REpresentational State Transfer)의 약어로 웹을 이용할 때 제약 조건들을 정의하는 소프트웨어 아키텍처 스타일이다. HTTP URL을 통해 자원(Resource)를 명시하고 HTTP Method(GET, POST, PUT, DELETE)를 통해서 해당 자원(URL)에 대한 CRUD(Create, Read, Update, Delete)를 적용하는 것을 의미한다. 한마디로 HTTP의 장점을 살리고자 하는 통신 규약이라고 볼 수 있다. RESTful API는 이러한 규약을 바탕으로 리소스 중심으로 설계하고 기능에 맞게 HTTP Method를 사용하여 설계된 API이다.

• GET : 지정된 URL에서 리소스의 표현을 조회
• POST : 지정된 URL에서 신규 리소스를 생성
• PUT : 지정된 URL에 리소스를 생성하거나 업데이트
• PATCH : 리소스의 부분 업데이트
• DELETE: 지정된 URL의 리소스를 제거

REST 특징

REST 아키텍처에 적용되는 6가지 제한 조건

• 인터페이스 일관성 : 일관적인 인터페이스로 분리되어야 한다.
• 무상태 : 각 요청 간 클라이언트의 context, 세션과 같은 상태정보를 서버에 저장하지 않는다.
• 캐시 처리 가능 : 클라이언트는 응답을 캐싱할 수 있어야 한다. 캐시를 통해 대량의 요청을 효율적으로 처리할 수 있다.
• 계층화 : 클라이언트는 대상 서버에 직접 연결되어 있는지, Proxy를 통해서 연결되었는지 알 수 없다.
• Code on demand : 자바 애플릿이나 자바스크립트의 제공을 통해 서버가 클라이언트를 실행시킬 수 있는 로직을 전송하여 기능을 확장시킬 수 있다.
• 클라이언트/서버 구조 : 아키텍처를 단순화시키고 작은 단위로 분리함으로써 클라이언트-서버의 각 파트가 독립적으로 구분하고 서로 간의 의존성을 줄인다.

REST 구성요소

1. 자원(Resource) : HTTP URL
2. 자원에 대한 행위 : HTTP Method
3. 자원에 대한 표현(Representations)

REST API 설계 Rules 및 예시

1. 소문자를 사용한다.

• 대문자는 때로 문제를 일으키는 경우가 있기 때문에 URI를 작성할 때는 소문자를 선호한다.

❌ http://pie8.tistory.com/users/Post-Comments ⭕ http://pie8.tistory.com/users/post-comments

2. 언더바(_) 대신 하이픈(-)을 사용한다.

• 가독성을 위해 긴 path를 표현하는 단어는 하이픈(-)으로 구분하는 것이 좋다.
• 프로그램의 글자 폰트에 따라 언더바 문자는 부분적으로 가려지거나 숨겨질 수 있다.

❌ http://pie8.tistory.com/users/post_comments ⭕ http://pie8.tistory.com/users/post-comments

3. 마지막에 슬래시(/)를 포함하지 않는다.

• 후행 슬래시(/)는 의미가 전혀 없고 혼란을 야기할 수 있다.
• URI내의 모든 문자는 리소스의 고유 ID에 포함된다. URI가 다르면 리소스도 다르기 때문에 명확한 URI를 생성해야한다.

❌ http://pie8.tistory.com/users/ ⭕ http://pie8.tistory.com/users

4. 행위를 포함하지 않는다.

• 행위는 URI 대신 Method를 사용하여 전달한다.

❌ POST http://pie8.tistory.com/users/post/1 ⭕ PUT http://pie8.tistory.com/users/1

5. 파일 확장자는 URL에 포함시키지 않는다.

• 파일 확장자는 URI에 포함하지 말아야한다. 대신 Content-Type 헤더를 통해 전달되는대로 미디어 타입을 사용하여 body 콘텐츠를 처리한느 방법을 결정한다.
• Rest API 클라이언트는 HTTP에서 제공하는 형식 선택 메커니즘인 Accept 요청 헤더를 활용하도록 권장해야한다.

❌ http://pie8.tistory.com/users/photo.jpg ⭕ GET http://[pie8.tistory.com](http://pie8.tistory.com)/users/photo HTTP/1.1 Host: tngus.tistory.com Accept: image/jpg

6. 전달하고자 하는 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 사용한다.

❌ http://pie8.tistory.com/course/writing ⭕ http://pie8.tistory.com/course/write

7. URI에 작성되는 영어를 복수형으로 작성한다.

하나의 인스턴스를 복수형으로 표시하는게 문법적으로 맞지 않겠다고 생각할 수 있지만 URI의 형식을 복수형으로 사용하는 것이 실무에서 많이 사용되고 있다.

⭕ http://pie8.tistory.com/students/324832/courses

참고

https://cocoon1787.tistory.com/540