1강. REST는 기술이 아니라 약속(Contract) 이다

🤔 Question

👉 REST API를 설계할 때 흔히 이런 질문을 합니다. "GET, POST 잘 쓰면 REST 아닌가요?" "URI만 예쁘게 만들면 좋은 API 아닌가요?" 하지만 실무에서 진짜 문제는 다른 곳에서 터집니다. API를 배포했는데 다른 팀 서비스가 갑자기 깨지고, 모바일 앱이 업데이트 없이 동작하지 않고, 배포 때마다 장애가 반복됩니다. 그 이유는 대부분 하나입니다.

 

👉 REST를 기술이 아니라 ‘약속(Contract)’으로 보지 않았기 때문입니다.

 

🎯 REST를 CRUD 기술로 오해하는 이유

대부분의 REST 설명은 이렇게 시작합니다. GET → 조회 POST → 생성 PUT → 수정 DELETE → 삭제 그래서 REST = "HTTP 메서드로 CRUD 하는 기술" 이라고 오해합니다. 하지만 이건 표현 방법일 뿐, REST의 본질이 아닙니다. 진짜 REST의 핵심은 👉 서로 다른 시스템이 지켜야 할 ‘약속’을 만드는 것입니다.

 

🎯 API는 팀과 팀 사이의 계약서

MSA 환경에서는 하나의 서비스가 다른 여러 서비스의 API를 호출합니다. 주문 서비스 → 결제 서비스 프론트엔드 → 사용자 서비스 외부 파트너 → 우리 공개 API 이때 API는 단순한 코드가 아니라

👉 팀과 팀 사이에 체결된 계약서입니다.

 

계약서에는 이런 내용이 담깁니다.

✔ 어떤 요청을 보내면

✔ 어떤 형태의 응답이 돌아오며

✔ 어떤 에러가 발생할 수 있는지

이 약속이 깨지면, 코드가 아니라 비즈니스가 멈춥니다.

 

🎯 나쁜 API 변경의 실제 예시

{
  "userId": 10,
  "name": "Alice"
}

{
  "id": 10,
  "name": "Alice"
}

개발자는 "userId → id 로 이름만 바꿨을 뿐"이라고 생각합니다. 하지만 이 순간

👉 앱, 다른 서비스, 외부 파트너 시스템이 모두 깨집니다. 이것이 바로 계약(Contract)을 깨뜨린 변경입니다.

 

🎯 좋은 REST API의 정의

좋은 REST API는 "URI가 예쁜 API"가 아닙니다. 👉 변경되어도 쉽게 깨지지 않는 API 👉 소비자가 예측 가능한 API 👉 문서가 없어도 신뢰 가능한 API 이 모든 것은 결국 계약을 얼마나 신중하게 설계했는가에 달려 있습니다.

 

🎯 그래서 이 강의에서 다룰 것

이번 강의 시리즈에서는 REST를 기술이 아니라 계약 관점에서 다룹니다.

✔ API를 문서가 아니라 계약으로 고정하는 방법

✔ 변경에 강한 설계 규칙

✔ 에러까지 포함한 신뢰 가능한 규약 만들기

✔ MSA 조직에서 계약을 자동 검증하는 방법

이제 REST를 "잘 짜는 기술"이 아니라 "깨지지 않는 약속"으로 다시 보게 될 것입니다.

 

☔ 정리

👉 REST의 본질은 CRUD가 아니라 Contract입니다. 👉 API는 코드가 아니라 팀 간 약속입니다. 👉 약속이 깨지면 시스템이 아니라 비즈니스가 깨집니다. REST를 다시 정의하면, "서로 신뢰할 수 있도록 만드는 기술"입니다.

 

 

If I was of any help to you, please buy me coffee 😿😢😥

If you have any questions, please leave them in the comments

Buy me a coffee

▶ Youtube Sub

🧭 References

[1] reference : https://doctorson0309.tistory.com/

[2] Ads : https://apps.apple.com/us/app/beluga-classic-film-filters/id6744041061