API 설계 원칙

API의 특수성

1. API는 다른 서비스를 개발하기 위한 중간 제품으로 인지된다.
2. API가 변화하게 될 때 해당 API를 사용한 모든 서비스에 문제를 야기할 수 있음.

API 설계 원칙

협업 : 다양한 이해관계자들의 충분한 합의가 필요함. 성과 : 가치, 도메인을 중심에 둘 것 (쓸모있는 것) 기술 : 기술 선택은 용도에 맞출 것(기술중심이 아닐것) 약속 : API는 고객과의 약속임. 큰 책임을 고려할것 문서 : 무엇보다 문서가 우선될 것

문서작성의 흐름

개발 중심 흐름

1. 개발부터하고 그 결과를 문서로 생성함
2. 개발이 변경되면 자동생성기가 문서를 변화시킴
3. 문서를 기반으로 개발코드를 만들어야함.

API설계 원칙 흐름

1. 5대 원칙에 근거하여 API문서가 먼저 작성됨
2. 도메인이나 고객의 변화에 따라 API의 변화가 생겨날
3. 실제 개발되는 코드나 언어와 무관하게 문서가 운영됨

개발을 못하는 기획과 할경우 개발자가 API DOC문서작성의 주체가 되어 개발중심으로 되는 경우가 문제임. 기획자가 API설계는 할 줄 알아야함.

문서작성 요령

ADDR프로세스에 따라 작성

1. 도메인분석을 통한 작업스토리 추출 및 디지털기능식별(웹으로 가능한지여부) :

2. EX) 나는 무엇에 관심이 있어서 그걸 CALL해서 어떤 데이터를 받는다.

3. EX) 헬스자체는 못하지만 헬스장 운동 기록은 디지털기능으로 가능

4. 작업스토리별 액티비티 단계 캡처

5. EX) 절차 프로세스 확인 : 장바구니 담기 -> 포인트사용 -> 결제

6. 이벤트스토밍의 네러티브를 이용한 API경계 실별(애그리거트 분리)

7. 식별된 바운디드컨텍스트 내의 구체적인 개별 API정의

8. REST구조에 맞는 실제 설계

9. DDD등 여러 기법 동원

10. 유저스토리매칭, 작업스토리, 스토리스토밍, 유즈케이스, 예제매핑 등

OPEN API

하나의 규격, 많은 API를 기술 가능하고 사용이 많음.

요청, 응답의 정의

1. 메소드 적용을 얼마나 엄격하게 할 것인가? PUT, POST

2. 멱등성의 범위를 어떻게 정의할 것인가?

3. 요청 변수는 공통 포멧을 적용할 것인가?

4. 인증, 인가, 상태를 어떻게 처리할 것인가?

5. 모든 응답의 공통포멧을 적용할 것인가?

6. 응답의 상태별 공통 포멧을 적용할 것인가?

7. 정상응답의 페이로드는 공통 포멧을 적용할것인가? OBJECT? ,LIST?

8. 응답코드의 공통 기준을 적용할 것인가?

9. 하이퍼미디어를 적용할것인가? (동적 ENDPOINT, 실행해봐야 ENDPOINT를 알 수 있음.)/ 해태우스

도메인주도

1. 비지니스를 잘 이해했다 = 돈을 많이 벌고 있다.
2. 대부분 돈을 많이 벌고 있지 않음.
3. 돈 벌고 있는 대부분도 왜 돈이 벌렸는지 잘 모름
4. 사업당사자도 비지니스로서의 도메인을 잘 이해하지 못함.
5. 따라서 개발자가 비지니스를 잘 이해한다는건 거의 불가능에 가까움.

개발자가 알 수 있는것

1. 관찰해보니 그 일을 실제하고 있음.
2. 비지니스 경쟁자가 어떤일을 하고 있음
3. 비지니스 관련 법령이나 암묵지로 해야할 일이 있음

비지니스의 구분

1. 크게 돈 되는 부분 - 핵심 하위 도메인
2. 작게 돈 되는 부분 - 일반 하위 도메인
3. 돈 벌려면 해야하는 부분 - 지원 하위 도메인

문제점

1. 뭐가 왜 돈 되는지 사업 당사자도 잘 모름
2. 핵심 하위 도메인이라고 생각했던게 도메인 자체가 아니었음
3. 일반 하위 도메인이라고 생각한 부분으로 회사가 돌아감 ex) 쇼핑몰로 돈벌려고 했는데 AWS로 돈범
4. 지원하위 도메인이라고 생각한 부분으로 회사가 돌아감 ex) cs게시판 잘 운영하다보니 cs회사가 독립됨

하위 도메인은 개발하는 방법

1. 돈을 벌려면 (개발)비용을 최적화해야 함.
2. 비용이 절약되는 구조가

대부분의 핵심 도메인의 내제화는 허상

1. 국내 기업 대부분은 핵심 도메인 구현에 외주업체 사용
2. 주요 기업의 잉여자본금은 외부 투자사에 위임함.
3. 개발 내부에도 많은 외주 인원들이 상주함.
4. 더 나아가 ㅎ인공지능 등 핵심 개발물 진행에 주도적인 외주 인원도 많음. ex) ai스타트업 대부분 openAI api임, 오픈소스도 사실상 외주솔루션
5. 핵심 도메인은 돈을 벌어야하기 때문에 고도화된 기술을 사용할수록 대응이 느려져 오히려 모순적, 핵심도메인이야말라 saas나 외주의 경연장

유비쿼터스 언어

• 비지니스도메인용어가 투명하지 않음. (새로운 개념의 언어가 생겨남)
• 도메인 전문가가 IT서비스에 대한 이해가 없는 경우가 흔함.
• IT프로젝트를 도메인 전문가가 주도할 수 없음. => 결국 유비쿼터스 언어는 도메인이 IT에 수용되는 형태로 정의됨.

유비쿼터스 그로서리

1. 서로 공유하기 쉽고 편집하기 쉬운 온라인 동시 편집환경이 좋음
2. 구글 스프레드시트는 누구나 접근하기 좋은 구조
3. 그로서리를 가장 많이 사용하는 곳은 기획서 작성임
4. 따라서 실질적인 그로서리는 피그마 내부에서 정의되는 경우가 대부분

도메인 커뮤니케이션

1. 도메인지식에서 코드로 단반향으로 흐르는 것처럼 묘사
2. 실제로는 개발팀의 도메인을 바탕으로 작성된 서비스를 도메인팀이 사용한 피드백을 바탕으로 수정됨
3. 애자일 이론에서도 강조하듯 가장 확실한 커뮤니케이션은 제품 출시임.
4. 개발팀의 '이거대로 하면 이런 문제가 있는데요? 어 그러네요.'의 과정이 보여짐
5. 유비쿼터스 언어는 중복된의미의 단어를 하나로 통합하는 과정 (사용자, 유저, 계정) 개념을 명확하게하지 않고 불러주는대로 만들다보면 위와같이 같은 개념을 다른말로 만들어놓는 불상사 발생
6. 도메인 전문가에게 중요한건 도메인이 잘 전달되었나가 아님. 기존의 도메인을 완전 다르게 표현 혹은 다른 기능을 전달해도 그게 도메인 내에서 가치가 있으면 관심있음

스프린트에서 도메인에게 전달할건 도메인 내에서 가치를 발휘하는가