REST API (=RESTful API)
RESTFUL API설계시
-
URI(Endpoint) 설계:
- 자원을 나타내는 URI를 명확하게 설계합니다.
- URI는 명사형으로 사용하고, 복수형 명사를 사용하여 컬렉션을 표현합니다.
- 자원을 식별하기 위해 ID나 다른 고유한 식별자를 사용합니다.
-
HTTP Method 활용:
- HTTP Method를 올바르게 활용하여 각 작업을 수행합니다.
- GET: 데이터 읽기
- POST: 새로운 데이터 생성
- PUT: 데이터 수정
- DELETE: 데이터 삭제
- PATCH: 일부 데이터 업데이트 (선택적으로 사용)
-
HTTP 상태 코드:
- 각 응답에 적절한 HTTP 상태 코드를 반환합니다.
- 200 OK, 201 Created, 204 No Content, 400 Bad Request, 404 Not Found, 500 Internal Server Error 등을 사용합니다.
-
URI 파라미터와 쿼리 스트링 활용:
- 필요한 경우 URI 파라미터 또는 쿼리 스트링을 사용하여 추가 정보를 전달합니다.
-
헤더 활용:
- HTTP 헤더를 사용하여 데이터 형식, 권한 등의 정보를 전달합니다.
- Content-Type, Authorization 등을 활용합니다.
-
JSON 또는 XML 응답:
- 데이터 형식으로 JSON 또는 XML을 사용합니다.
- 응답 데이터는 클라이언트가 이해하기 쉽게 구조화되어야 합니다.
-
에러 처리:
- 에러가 발생할 경우 적절한 에러 응답을 반환합니다.
- 에러 메시지와 에러 코드를 포함하여 클라이언트에게 에러 정보를 제공합니다.
-
HATEOAS (Hypermedia as the Engine of Application State):
- 클라이언트에게 다음 가능한 작업에 대한 링크를 제공하여 연결된 API를 만듭니다.
- 예를 들어, 리소스에 대한 링크가 포함된 응답을 반환하여 클라이언트가 쉽게 탐색할 수 있도록 합니다.
-
보안:
- API 보안을 위해 HTTPS를 사용하고, 권한 및 인증을 구현합니다.
- 사용자 인증 및 권한 부여를 관리하여 데이터 보호를 보장합니다.
-
테스트:
- 코드의 유단 테스트 및 통합 테스트를 수행하여 API의 안정성을 확인합니다.
-
문서화:
- API를 사용하는 방법을 상세하게 문서화하여 개발자에게 API를 이해하고 사용하는 데 도움을 줍니다.
-
버전 관리:
- API 버전 관리를 통해 변경사항을 관리하고 역호환성을 유지합니다.
데이터베이스 정규화 (Database normalization)
- 엔티티 간 반복적인 연결을 피하고 중복된 원형 연결(Circular Reference)을 만들지 않아야 함.
- URI(Uniform Resource Identifier), URL(Uniform Resource Locator), URN에 대한 차이를 구분
- RESTful API Request 및 Response 설계에 중요한 요소
HTTP Request 구성요소 설계
- HTTP Method, URI(Endpoint)의 설계가 중요
- HTTP Method (GET, POST, PUT, DELETE)의 목적과 사용법을 고려
- URI는 자원을 표현하고 그 자원에 접근하는 방법을 설명해야 함
- API 설계 시 CRUD 및 Functional 영역을 분리하는 것이 중요
- 다양한 URI, URL, Endpoint, Query 및 동사 사용 방법을 고려
HTTP Response 구성요소 설계
- HTTP Response의 구성요소는 상태 라인, 헤더, 본문으로 구성
- 상태 코드 (Status Code)를 사용하여 요청 결과를 표시
- 상태 코드는 Informational, Successful, Redirection, Client Error, Server Error 등으로 구분
- 각 상태 코드는 HTTP 버전, 상태 코드, 상태 메시지로 구성
- 헤더 (Headers)는 Response 부가 정보를 반환하고 Content-type을 사용하여 데이터 형식을 표현
- 본문 (Body)에는 실제 데이터가 포함