[Develop] RESTful API

웹서버를 만들면서, 클라이언트와 데이터를 주고받는 API를 작업했다. 클라이언트에서 요구하는대로 API를 작업하고 테스트를 하면서, 웹 API의 베스트 프랙티스를 찾아보았다. 아래 링크에서 도움을 많이 받고 내용을 정리하려한다.

 

Refrence

https://learn.microsoft.com/ko-kr/azure/architecture/best-practices/api-design

웹 API 디자인 모범 사례 - Azure Architecture Center

https://www.redhat.com/ko/topics/api/what-is-a-rest-api

REST API, RESTful API, 레스트풀 API란? 개념과 특징 탐색

 

1.  API 설계 원칙

 

1. API의 명확한 목적을 정의한다.

• 설계하려는 API의 목적, 가치를 명확하게 정의하고, 설계해야한다.

2. 일관성을 유지한다.

• 설계하려는 모든 API에서 일관된 스타일, 형식, 규칙을 적용해야한다.

3. 표준화된 프로토콜을 사용한다.

• HTTP, HTTPS 등 표준 프로토콜을 사용하여, 상호 운용성을 보장해야한다.

4. RESTful API 설계

• RESTful 설계를 따르고, 리소스 기반의 접근 방식을 사용해야한다.
• URI를 통해 리소스를 명확하게 표현하고, HTTP 메서드를 이용하여 작업을 수행해야한다.

*HTTP Method : GET, POST, PUT, DELETE 등

 

REST는 Representational State Transfer의 약자로, 웹 아키텍처 스타일을 말한다. RESTful API는 REST 스타일로 제약 조건을 준수하고 서비스와 상호작용할 수 있도록 하는 API다.

 

2. API 설계 모범 사례

 

1. 명확한 URI 설계

• 리소스를 식별할 수 있는 명확하고 직관적인 URI를 설계합니다.
• 예: /users/{userId}/orders/{orderId}

2. HTTP 메서드의 올바른 사용

• GET: 리소스 조회
• POST: 새로운 리소스 생성
• PUT: 기존 리소스 업데이트
• DELETE: 리소스 삭제

3. 상태 코드 사용

• 적절한 HTTP 상태 코드를 사용하여 클라이언트가 요청의 결과를 쉽게 이해할 수 있도록 합니다.
• 예: 200 (성공), 201 (생성됨), 400 (잘못된 요청), 404 (찾을 수 없음), 500 (서버 오류)

4. API 버전 관리

• API의 변경 사항을 관리하기 위해 버전 관리를 도입합니다.
• URI 경로에 버전을 포함하는 방식(예: /v1/)을 권장합니다.

5. 페이징, 필터링, 정렬

• 많은 데이터를 반환하는 경우 페이징을 지원하여 응답 크기를 줄입니다.
• 필터링과 정렬 기능을 제공하여 클라이언트가 원하는 데이터를 효율적으로 검색할 수 있도록 합니다.

6. 보안

• HTTPS를 사용하여 데이터 전송을 암호화합니다.
• OAuth2와 같은 인증 및 권한 부여 메커니즘을 사용하여 API 접근을 제어합니다.

7. 문서화

• API 문서를 작성하여 개발자가 API를 쉽게 이해하고 사용할 수 있도록 합니다.
• Swagger(OpenAPI)와 같은 도구를 사용하여 인터랙티브한 문서를 제공할 수 있습니다.

8. 테스트와 모니터링

• API 테스트를 자동화하여 안정성을 높이고, 문제 발생 시 빠르게 대응할 수 있도록 합니다.
• API의 사용량과 성능을 모니터링하여 지속적으로 개선합니다.