아래 글은 원글을 바탕으로 ChatGPT로 다시 작성하였습니다.
RESTful API를 설계하는 데 있어 단순히 리소스를 정의하고 엔드포인트를 작성하는 것만으로는 부족합니다. API가 지속 가능하며 재사용 가능한 구조를 갖추기 위해서는 명확한 설계 절차와 기준이 필요합니다. 이번 글에서는 RESTful API 설계 절차를 요약하고, 설계 과정에서 떠오를 수 있는 질문들을 함께 살펴보겠습니다.
RESTful Web API 설계 절차
RESTful API 설계를 위한 기본적인 절차는 다음과 같이 7단계로 나눌 수 있습니다.
1. 의미 체계 서술자 나열
API를 통해 클라이언트가 얻거나 넣고자 하는 정보를 나열합니다.
→ 예: 클라이언트가 필요한 데이터, 가능한 작업들 등
2. API 상태 다이어그램 작성
API의 상태와 상태 간 전이를 시각화하여 다이어그램으로 작성합니다.
→ 예: 상태 간 연결, 가능한 작업 흐름 등
3. 이름 조정하기
기존 표준(IANA)의 이름과 서술자들을 활용하거나, 도메인에 맞는 새로운 이름을 정의합니다.
→ 권장: ALPS와 같은 기술로 프로파일 재사용
4. 미디어 유형 선택 또는 정의
API에 적합한 미디어 유형(예: Collection+JSON, AtomPub)을 선택하거나 새로 정의합니다.
5. 애플리케이션 의미 체계 기술 프로파일 작성
선택한 미디어 유형에 맞는 구체적인 프로파일을 설계합니다.
6. 코드 작성
상태 다이어그램과 의미 체계를 기반으로 HTTP 서버를 개발합니다.
7. 배포 및 문서화
‘홈페이지’ 리소스를 포함하여 API를 배포하고, 메타데이터 및 문서를 작성합니다.
→ 추가 작업: 새로운 연결 관계 등록, API 문서화
RESTful API 설계에서 떠오르는 질문들
- API 설계 단계의 순서 유연성
• 7단계 절차는 항상 순서대로 진행해야 할까? 특정 단계는 병렬적으로 수행하거나 순서를 변경할 수 있을까? - 상태 다이어그램과 클라이언트 요구사항 간의 조화
• 클라이언트 요구사항이 자주 변하는 환경에서 상태 다이어그램을 고정적으로 설계하려면 어떤 전략이 필요할까? - 단순 RESTful API vs 완전한 하이퍼미디어 API
• 설계 7단계를 단순 RESTful API와 하이퍼미디어 중심 API에 적용할 때, 가장 큰 차이점은 무엇일까? - 실제적인 설계 제약
• 네트워크 속도, 데이터 형식 제한과 같은 기술적 제약이 설계 단계에 어떤 영향을 미칠까? - API 상태 다이어그램의 재사용 가능성
• 상태 다이어그램이 여러 애플리케이션이나 도메인에서 재사용 가능할까? 이를 일반화하려면 어떤 요소를 고려해야 할까? - 배포 단계에서의 예외 처리
• API 배포 후 예상치 못한 요구사항이나 문제가 발생했을 때, 어떤 설계 단계를 가장 먼저 되돌아봐야 할까? - 의미 체계 서술자의 범위 결정
• 의미 체계 서술자를 나열할 때, 불필요한 세부 정보를 배제하기 위한 기준은 무엇일까? - 홈페이지 리소스의 설계 중요성
• ‘홈페이지’ 리소스 설계를 실패하면 클라이언트에 어떤 불편을 초래할 수 있을까? 이를 방지하기 위한 기본 규칙은? - 기존 프로파일과의 호환성
• 기존에 정의된 프로파일과 내 애플리케이션의 의미 체계 서술자가 충돌할 경우, 이를 해결하는 방법은? - 미디어 유형 선택의 실질적 기준
• API 사용자들이 가장 선호하는 미디어 유형은 무엇이며, 이를 선택하지 못했을 때 발생할 수 있는 불편함은?
