REST API(Representational State Transfer API)

REST API란 REST를 기반으로 만들어진 API를 의미한다.

 

REST란?

클라이언트와 서버 간의 통신을 위한 아키텍처 스타일 중 하나로,

HTTP 프로토콜을 기반으로 하며, 자원(Resource)을 정의하고 해당 자원에 대한 주소를 지정하여 해당 자원의 상태를 주고 받는 것을 목적으로 한다.

 

REST API를 자판기에 비유해 생각해보면 쉽게 이해할 수 있다.

 

자판기는 버튼을 누르거나 동전을 넣어서 음료나 과자를 받을 수 있다. 이때 음료와 과자는 자원(Resource)이 되고 음료와 과자의 이름이 식별자(URI)가 된다고 생각하면 된다. 또한 자판의 버튼은 요청(request)이고, 받은 음료나 과자는 응답(response)에 해당하게 된다.

 

REST API 작성

REST API를 작정하는 방법은 프로그래밍 언어와 프레임워크에 따라 달라질 수 있다. 하지만 일반적으로 다음과 같은 단계를 따르게 된다.

 

1. 요구사항 및 자원식별 : 먼저 어떤 자원을 다룰 것인지, 그 자원에 어떤 동작을 수행할 것인지를 정의해야한다. 이는 자원의 종류, 필드, 관계 등을 포함한다.

2. HTTP 메소드 결정 : 각 자원에 대한 어떤 HTTP 메소드를 허용할 것인지 결정해야 한다. 주로 사용되는 메소드는 GET, POST, PUT, DELETE 등이 있다.

3. 엔드포인트 설계 : 각 자원과 메소드에 대한 엔드포인트를 설계한다. 이 엔드포인트는 클라이언트가 서버의 특정 동작을 요청할 때 사용되는 URL이다.

4. 데이터 포맷 결정 : REST API는 주로 JSON이나 XML 형식의 데이터를 주고 받는다. 데이터의 포맷을 결정하고 이에 맞춰 요청 및 응답을 처리해야한다.

5. 구현 : 선택한 프로그래밍 언어와 프레임워크를 사용하여 REST API를 구현한다. 요청을 처리하고 응답을 생성하는 코드를 작성하고, 이를 서버에 배포하여 클라이언트가 해당 API에 접근할 수 있도록 해야한다.

6. 테스트 : 작성한 API가 기대한 대로 동작하는지 확인하기 위해 테스트를 수행해야 한다. 이를 통해 잠재적인 버그나 문제를 식별하고 수정할 수 있다.

7. 문서화 : 작성한 REST API에 대한 문서를 작성하여 다른 사용자가 해당 API를 쉽게 이해하고 사용할 수 있도록 해야한다. 이는 API의 엔드포인트, 요청 및 응답포맷, 인증방법 등을 설명해야 한다.

 

REST API 작성 예시

사용자가 포스트를 작성하고 댓글을 달며 상호작용할 수 있는 기능을 제공하는 커뮤니티 사이트를 만든다고 가정해보고 이를 위한 간단한 REST API를 정의해보겠다.

 

1. 사용자 관련 API

• 사용자 등록 : POST /users
• 사용자 정보 가져오기 : GET /users/{id}
• 사용자 정보 업데이트 : PUT /users/{id}
• 사용자 삭제 : DELETE /users/{id}

2. 포스트 관련 API

• 포스트 목록 가져오기 : GET /posts
• 특정 포스트 가져오기 : GET /posts/{id}
• 새로운 포스트 작성 : POST /posts
• 포스트 업데이트 : PUT /posts/{id}
• 포스트 삭제 : DELETE /posts/{id}

3. 댓글 관련 API

• 댓글 목록 가져오기 : GET /posts/{post_id}/comments
• 새로운 댓글 작성 : POST /posts/{post_id}/comments
• 댓글 업데이트 : PUT /posts/{post_id}/comments/{comment_id}
• 댓글 삭제 : DELETE /posts/{post_id}/comments/{comment_id}

4. 기타 API

• 인기 있는 포스트 목록 가져오기 : GET /popular-posts
• 특정 주제에 대한 포스트 목록 가져오기 : GET /topics/{topic_id}/posts
• 포스트 좋아요 : POST /posts/{post_id}/like

간단한 REST API 예시를 정리해보았다. 물론 실제로는 프로젝트의 요구사항과 상황에 따라 더 많은 API 엔드포인트가 필요할 수 있다.

 

---

공부하면서 궁금했던 것들

1. REST API를 정의하는 작업에 선행되는 것이 데이터 설계인가?

• 데이터 설계는 API의 기본적인 구조와 동작에 영향을 미치기 때문에 먼저 데이터 모델을 설계하고나서 REST API를 정의하는 것이 일반적이다. 데이터 모델을 먼저 설계해야 어떤 자원을 다룰 것인지에 대한 명확한 이해를 얻을 수 있고 이를 기반으로 REST API의 자원과 엔드포인트를 정의할 수 있기 때문이다.

2. REST API를 작성하는 규칙이 있을까?

• URI는 동사보다는 명사를, 대문자보다는 소문자를 사용해야 한다.
• 마지막에 슬래시(/)를 포함하지 않는다.
• 언더바 대신 하이폰을 사용한다.
• 파일확장자는 URI에 포함하지 않는다.
• 행위를 포함하지 않는다.