1. REST API란?
REST(Representational State Transfer)는 HTTP 네트워크 상의 리소스(Resource, 자원)를 정의하고 해당 리소스를 URI라는 고유한 주소로 접근하는 접근 방식을 의미하며, REST API란 REST 방식을 통해서 리소스에 접근하기 위한 서비스 API를 지칭한다..
자원(Resource) : REST 아키텍처에서 모든 것은 자원으로 간주된다. 자원은 서버에 저장된 데이터나 서비스 등을 의미하며, 각 자원은 고유한 URI(Uniform Resource Identifier)로 식별된다.
메소드(Method) : 자원에 대한 행위는 HTTP 메소드를 통해 정의된다. 주로 사용되는 메소드는 다음과 같다.
- GET: 자원을 조회한다.
- POST: 새로운 자원을 생성한다.
- PUT: 자원을 갱신한다.
- DELETE: 자원을 삭제한다.
2. REST의 장단점
장점
- HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구출할 필요가 없다.
- HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해 준다.
- HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
- Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.
- REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
- 여러 가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.
- 서버와 클라이언트의 역할을 명확하게 분리한다.
단점
- 표준이 자체가 존재하지 않아 정의가 필요하다.
- HTTP Method 형태가 제한적이다.
- 브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 정보의 값을 처리해야 하므로 전문성이 요구된다.
- 구형 브라우저에서 호환이 되지 않아 지원해주지 못하는 동작이 많다.(익스폴로어)
3. 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
Share article