REST API URL 규칙

API 개발을 하는데 있어서 URI를 어떻게 명명할지에 대한 정리를 하기 위해 포스팅 하였다.

 

1. RESTful API 란

---

Rest : Representational State Tranfer의 약자로 웹을 이용할때 제약조건들을 정의하는 소프트웨어 아키텍처 스타일.

HTTP URL 을 통해서 자원(Resource)을 명시하고 HTTP Method(GET, POST, PUT, DELETE)를 통해 해당 자원(URL)에 대한 CRUD를 적용하는 것을 의미한다.

한마디로 HTTP의 장점을 살리고자 하는 통신규약 

 

2. REST 특징

---

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

 

3. REST 구성요소

---

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

 

4. REST API 설계 Rules 및 예시

---

1. 소문자를 사용한다.

 

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

❌ http://dev-cool.tistory.com/users/Post-Comments

⭕ http://cocoon1787.tistory.com/users/post-comments

---

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

 

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

❌ http://dev-cool.tistory.com/users/post_comments

⭕ http://dev-cool.tistory.com/users/post-comments

---

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

 

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

❌ http://dev-cool.tistory.com/users/

⭕ http://dev-cool.tistory.com/users

---

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

 

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

❌ POST http://dev-cool.tistory.com/users/post/1

⭕ PUT http://dev-cool.tistory.com/users/1

---

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

 

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

❌ http://dev-cool.tistory.com/users/photo.jpg

⭕ GET http://dev-cool.tistory.com/users/photo
   HTTP/1.1 Host: dev-cool.tistory.com Accept: image/jpg

---

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

❌ http://dev-cool.tistory.com/course/writing

⭕ http://dev-cool.tistory.com/course/write

---

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

 

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

⭕ http://api.college.com/students/3248234/courses

 

출처 :
https://cocoon1787.tistory.com/540

RESTful API 의미와 설계 규칙

https://dzone.com/articles/7-rules-for-rest-api-uri-design-1

7 Rules for REST API URI Design - DZone Integration