RESTful API란?
먼저, REST는 HTTP를 기반으로 클라이언트가 서버의 리소스에 접근하는 방식을 규정한 아키텍쳐이며, REST를 준수하는 API를 REST API라고 합니다.
📌 REST API의 세 가지 요소
자원(URI), 행위(HTTP요청 메서드), 표현(페이로드)
📌 REST API의 설계 원칙
- URI는 리소스를 표현해야 한다.
- 리소스에 대한 행위는 HTTP 요청 메서드로 표현한다.(URI에 표현하지 않는다.)
REST의 기본 원칙을 성실히 지킨 서비스 디자인을 Restful하다고 합니다.
RESTful API의 설계 원칙을 준수하여 각 리소스에 대해 일관된 메소드를 사용하면 API를 이해하기 쉽고 유지보수하기 편해집니다.
예시1) RESTful 하지 않은 예
**// 회원 관리시스템의 API 설계**
**회원 목록조회: http://test.com/member/read --> [GET]
회원 조회: http://test.com/member/{id}/read --> [GET]
회원 등록: http://test.com/member/create --> [POST]
회원 삭제: http://test.com/member/delete/{id} --> [DELETE]
회원 수정: http://test.com/member/update/{id} --> [PUT]
회원 수정: http://test.com/member/patch/{id} --> [PATCH]**API 요청에 대한 리소스 동작은 HTTP 요청 메서드를 통해 명확히 구분되며 URI는 리소스만을 나타내지만, 해당 리소스에 대한 읽기(read), 생성(create) 등의 동작을 포함하고 있습니다.
REST API의 설계 원칙을 지키지 못했으니 RESTful 하지 않습니다.
예시 2) RESTful한 API 예
**// 회원 관리시스템의 API 설계**
**회원 목록조회: http://test.com/member --> [GET]
회원 조회: http://test.com/member/{id} --> [GET]
회원 등록: http://test.com/member --> [POST]
회원 삭제: http://test.com/member/{id} --> [DELETE]
회원 수정: http://test.com/member/{id} --> [PATCH],[PUT]**URI는 일관되게 리소스만을 나타내며 API 요청 시 각 리소스 동작은 명확히 HTTP 요청 메서드로 구분됩니다. 이는 REST API의 설계 원칙을 따른 RESTful API입니다.
모든 상황에서 REST API의 설계원칙을 항상 지킬 수는 없습니다. 특히 HTML FORM 태그를 사용하여 API 요청을 처리할 때는 FORM이 GET 과 POST 요청만 지원하기 때문에 DELETE나 PUT과 같은 다른 HTTP 메서드를 사용하여 리소스 동작을 표현하는 것이 제한됩니다.
이런 경우에는 URI에 동사를 추가하여 URL을 형성하게 되며, FORM 태그를 사용하는 상황 이외에도 리소스 자원만을 표현한 URI와 HTTP 요청 메서드만으로 명확히 API를 이해하기 어려운 경우 URI에 동사를 포함시켜 설계합니다. 이를 컨트롤 URI라고 하며, 가독성과 명확성을 유지하기 위해 선택적으로 컨트롤 URI를 사용할 수 있습니다.
RESTful 디자인의 원칙적인 관점에서는 동사를 피하고 명사 중심의 URI를 사용하는 것이 권장되지만, 현실적인 제약 사항에 따라 동사를 사용하는 것이 더 유용할 수 있습니다. 중요한 것은 API가 일관성 있고 이해하기 쉽게 설계되어야 한다는 점입니다.
API 문서
설계된 API를 다른 사람이 잘 사용할 수 있도록 하기 위해 API 사용에 대한 설명이 필요한데, 어떻게 API를 사용해야 하는지에 대한 명확한 가이드라인을 제공하는 것이 API 문서입니다.
정확하고 이해하기 쉽게 잘 작성된 API 문서는 API를 제공하는 개발자와 API를 사용하는 개발자 간의 효율적이고 원활하게 커뮤니케이션 되도록 도와줍니다.
📌 API 문서 예시
- Kakao Developers 에서 다양한 REST API를 제공하는데, 그 API에 대한 문서를 확인해 볼 수 있습니다.
REST API 문서화 하기
API를 만들면 API를 사용할 사용자에게 API 명세서를 전달해줘야 합니다.
text파일이나 노션, 엑셀 등 작성 방법은 다양하지만, 수기로 작성해줘야합니다. 수기로 작성하면 오탈자 위험이 있습니다. api가 수정된다면 api 명세서도 수정이 되어야하지만 깜빡하고 수정해주지 않는다면 api 사용자는 이유모를 에러를 마주하게 될 수도 있습니다. 이러한 불편함을 벗어나기 위해 API를 문서화해주는 툴을 사용합니다.
위 포스트에서 소개해주는 여러 훌륭한 api 문서화 툴 중 Swagger를 사용한 예시를 보여드리겠습니다.
기존에 만들어둔 express 프로젝트의 memberAPI에 대해 Swagger를 이용해 API 문서를 생성해보았습니다.
swagger-jsdoc과 swagger-ui-express 패키지를 설치하고 swagger 사용 환경과 생성된 API 페이지에 대한 경로를 셋팅해준 뒤, REST API 파일에 각 API에 대한 API 엔드포인트, 요청/응답 형식, 매개변수에 대한 필수 정보를 jsdoc 형식의 주석으로 넣어주면 위와 같이 API 명세서가 만들어집니다.
⬇️ (GET_ /api/member 전체 회원 목록 조회에 대한 요청과 응답 예시)
API에 대한 요청과 응답 형식에 대해 설명한대로 문서화가 잘 되었습니다.
⬇️ (GET_ /api/member 전체 회원 목록 조회에 대한 요청 TEST)
생성된 API문서를 통해 쉽게 실제 데이터가 어떤 형태로 응답되는지 테스트해 볼 수도 있습니다.
<참고한 자료>
