[네트워크] REST API란 무엇인가?

REST API는 Representational State Transfer의 약자로, 2000년 로이 필딩(Roy Fielding)의 박사학위 논문에서 소개되었습니다. 로이 필딩은 HTTP의 설계에 관여했던 주요 인물로, 당시 웹(HTTP)의 잠재력이 제대로 활용되지 않는 점을 안타까워하며, 이를 최대한 활용할 수 있는 아키텍처 스타일로서 REST를 정의하였습니다.
REST는 인터넷 자원을 효율적으로 관리하고 설계하는데 초점을 둔 아키텍처로, 오늘날 API 설계에서 중요한 원칙으로 자리 잡았습니다.

REST API의 주요 구성 요소

REST API는 자원(Resource), 행위(Verb), 표현(Representation) 세 가지 요소로 구성됩니다.

1. 자원(Resource) - URI

URI(Uniform Resource Identifier)는 자원을 고유하게 식별하기 위한 식별자입니다.
URI는 자원을 표현하는 데 중점을 두며, 리소스의 이름은 일반적으로 명사로 작성합니다.

잘못된 예시
GET /members/delete/1

위 URI는 행위(delete)를 포함하고 있어 RESTful하지 않습니다.

올바른 예시
DELETE /members/1

행위는 HTTP Method로 표현하고, URI는 자원 자체를 나타냅니다.

2. 행위(Verb) - HTTP Method

HTTP Method를 사용하여 자원에 대한 행위를 정의합니다.
주요 HTTP Method는 아래와 같습니다

Method	역할
GET	리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져옵니다.
POST	POST를 통해 해당 URI를 요청하면 리소스를 생성합니다.
PUT	PUT를 통해 해당 리소스를 수정합니다.
DELETE	DELETE를 통해 리소스를 삭제합니다.

3. 표현(Representation)

클라이언트와 서버 간 데이터는 다양한 포맷으로 전달됩니다.
일반적으로 JSON이나 XML을 사용하며, 데이터 포맷은 Content-Type과 Accept 헤더로 명시합니다.

---

RESTful URI 설계 원칙

RESTful API의 URI를 설계할 때는 아래 원칙을 따르는 것이 중요합니다.

1. 슬래시(/)는 계층 관계를 나타냄

http://restapi.example.com/houses/apartments
http://restapi.example.com/animals/mammals/whales

2. URI 끝에 슬래시(/)를 사용하지 않음

URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며 URI가 다르다는 것은 리소스가 다르다는 것이고, 역으로 리소스가 다르면 URI도 달라져야 합니다. REST API는 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 슬래시(/)를 사용하지 않습니다.

http://restapi.example.com/houses/apartments/ (X)
http://restapi.example.com/houses/apartments  (O)

3. 하이픈(-) 사용

URI를 쉽게 읽고 해석하기 위해, 불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높일 수 있습니다.

http://restapi.example.com/best-selling-books

4. 밑줄(_) 사용 금지

글꼴에 따라 다르긴 하지만 밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지기도 합니다. 이런 문제를 피하기 위해 밑줄 대신 하이픈(-)을 사용하는 것이 좋습니다.(가독성)

http://restapi.example.com/best_selling_books (X)
http://restapi.example.com/best-selling-books (O)

5. 소문자 사용

URI 경로에 대문자 사용은 피하도록 해야 합니다. 대소문자에 따라 다른 리소스로 인식하게 되기 때문입니다. RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문이지요.

http://restapi.example.com/MyPage (X)
http://restapi.example.com/mypage (O)

6. 파일 확장자 제외

URI에 파일 확장자를 포함하지 않습니다. 대신 헤더(Accept)를 활용해 데이터 포맷을 지정합니다.

http://restapi.example.com/members/345/photo.jpg (X)
GET /members/345/photo HTTP/1.1  
Accept: image/jpg (O)

---

REST API 설계의 장점

1. 확장성: 표준 HTTP 프로토콜을 기반으로 하기 때문에 확장이 용이합니다.
2. 유연성: 다양한 클라이언트와 서버 환경에서 활용 가능합니다.
3. 가독성: 명확한 URI 설계와 HTTP Method 사용으로 이해하기 쉽습니다.
4. 표준화: HTTP의 표준 규격을 따르므로 API 설계와 통신이 간단합니다.

 

 

REST API는 현대 웹과 모바일 환경에서 필수적인 아키텍처입니다.
위에서 설명한 원칙을 준수한다면 더욱 효율적이고 직관적인 API를 설계할 수 있을 것입니다.

 

 

👀 HTTP 에 대한 내용을 한눈에 보고 싶다면 아래의 포스팅을 추천해요!

[네트워크] HTTP 요청과 응답

 

[네트워크] HTTP 메시지란?

[네트워크] HTTP 상태코드 정리