📌 REST API의 탄생
REST(Representational State Transfer)는 2000년도에 로이 필딩 (Roy Fielding)의 박사학위 논문에서 최초로 소개되었습니다. 로이 필딩은 HTTP의 주요 저자 중 한 사람으로 그 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다고 합니다.
그래서 REST API 란 무엇일까요?
📌 REST API
REST는 네트워크 아키텍처 원리의 모음입니다. 여기서 '네트워크 아키텍처 원리'란 자원을 정의하고 자원에 대한 주소를 지정하는 방법 전반을 일컫습니다. 쉽게 말해 REST API 는 REST의 규칙을 준수하고, RESTful 웹 서비스와 상호 작용할 수 있도록 하는 API(Application Programming Interface)입니다. REST API는 다음과 같이 구성되어 있습니다.
- 자원(RESOURCE) - URI
- 행위(Verb) - HTTP METHOD
- 표현(Representations)
API 는 무엇인가요?
애플리케이션 소프트웨어를 구축하고 통합하기 위한 정의 및 프로토콜입니다. 인터페이스는 두 애플리케이션 간의 서비스 계약이라고 할 수 있습니다.이 계약은 요청과 응답을 사용하여 두 애플리케이션이 서로 통신하는 방법을 정의합니다.
📌 REST 특징
1. URI는 정보의 자원을 표현해야 한다. (리소스명은 동사보다는 명사를 사용)
GET /members/delete/1
위와 같은 방식은 REST를 제대로 적용하지 않은 URI입니다. URI는 자원을 표현하는데 중점을 두어야하며, delete와 같은 행위에 대한 표현이 들어가서는 안됩니다.
2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현
위의 잘못된 예시를 HTTP Method를 통해 수정해 보겠습니다.
DELETE /members/1
- DELETE: HTTP 메서드로, 클라이언트가 서버에게 리소스 삭제를 요청하는 것을 나타냅니다.
- /members: 리소스의 컬렉션을 나타내는 경로입니다. 이 경우, "members"는 회원(사용자) 리소스의 그룹 또는 집합을 나타냅니다.
- /1: 특정 회원 리소스를 가리키는 식별자입니다. 이 경우, "1"은 회원의 고유한 식별자일 것입니다. 예를 들어, 사용자 아이디나 다른 유일한 식별자가 될 수 있습니다.
따라서, 위의 URI는 "회원"이라는 그룹에서 식별자가 "1"인 특정 회원을 삭제하도록 서버에게 요청하는 것을 의미합니다.
다른 예시를 들어보겠습니다.
회원정보를 등록하는 URI 는 다음과 같이 구성하면 됩니다.
GET /members/insert/2 (x) - GET 메서드는 리소스 생성에 맞지 않습니다.
POST /members/2 (o)
3. 적절한 HTTP Method 를 사용
HTTP Method 에는 총 8가지가 있지만 주로 사용하는 POST, GET, PUT, DELETE 이 4가지의 Method를 설명하겠습니다.이 4가지 Method만으로도 CRUD를 할 수 있습니다.
POST | POST를 통해 해당 URI를 요청하면 리소스를 생성합니다. |
GET | GET를 통해 해당 리소스를 조회합니다. 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다. |
PUT | PUT를 통해 해당 리소스를 수정합니다. |
DELETE | DELETE를 통해 리소스를 삭제합니다. |
📌 URI 설계시 주의할 점
1. 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용
http://restapi.example.com/houses/apartments
http://restapi.example.com/animals/mammals/whales
2. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
http://restapi.example.com/houses/apartments/ (X)
http://restapi.example.com/houses/apartments (0)
3. 하이픈(-)은 URI 가독성을 높이는데 사용
URI를 쉽게 읽고 해석하기 위해, 불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높일 수 있습니다.
4. 밑줄(_)은 URI에 사용하지 않는다.
글꼴에 따라 다르긴 하지만 밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지기도 합니다. 이런 문제를 피하기 위해 밑줄 대신 하이픈(-)을 사용하는 것이 좋습니다.(가독성)
5. URI 경로에는 소문자가 적합하다.
URI 경로에 대문자 사용은 피하도록 해야 합니다. 대소문자에 따라 다른 리소스로 인식하게 되기 때문입니다. RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문입니다.
<참고자료>
https://aws.amazon.com/ko/what-is/api/
API란 무엇인가요? - 애플리케이션 프로그래밍 인터페이스 설명 - AWS
GraphQL은 API용으로 특별히 개발된 쿼리 언어로서, 클라이언트에게 요청한 데이터만 제공하는 것을 우선으로 합니다. 또한 API를 빠르고 유연하며 개발자 친화적으로 만들도록 설계되었습니다. RES
aws.amazon.com
https://www.redhat.com/ko/topics/api/what-is-a-rest-api
REST API와 RESTful API(레스트풀 API)란? 의미와 특징 알아보기
REST API란 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처로, REST 아키텍처 조건을 준수하는 애플리케이션 프로그래밍 인터페이스입니다.
www.redhat.com