백엔드가 하는 일이 줄어든 경위
프론트엔드가 화면에 무엇이 어디 있는지를 정한다면, 백엔드는 거기에 무엇을 표시할지를 정한다. 둘 다 결국은 서버에서 요청을 받아 값을 돌려주는 일이다.
예전에는 이 구분이 지금 같지 않았다. 백엔드 도구가 화면까지 함께 그렸기 때문이다. 데이터의 모양을 잡는 부분, 화면을 그리는 부분, 둘 사이를 잇는 부분을 한 틀 안에 두는 방식이었고 이 구성을 MVC 패턴이라고 불렀다. Python에서는 Django가 그 자리를 오래 지켰다.
그러다 앞 편에서 본 대로 화면 그리는 일이 Next.js 쪽으로 넘어갔다. 그러자 백엔드의 세 부분 중 화면을 그리던 부분이 빠졌고, 남은 것은 무슨 값을 줄 것인가 하나가 됐다.
그 일만 하는 가벼운 도구가 자리를 차지했다. 그게 FastAPI다. 바이브 코딩에서 이 이름이 자주 나오는 건 지금 그 자리가 여기이기 때문이다. 언어마다 이런 도구가 여럿 있고 Java의 Spring, PHP의 Laravel이 같은 자리다.
API와 JSON
API는 프로그램끼리 서로 이어지는 창구다. 사람과 컴퓨터가 만나는 자리를 사용자 인터페이스라고 부르듯, 프로그램과 프로그램이 만나는 자리를 그렇게 부른다.
프론트엔드와 백엔드도 결국 이 창구로 대화한다. 프론트엔드가 화면에 그릴 틀을 준비해 두고 백엔드에 여기 채울 값을 달라고 요청하면, 백엔드가 답을 돌려준다.
그 답의 형식이 JSON이다. 중괄호를 열고 이름과 값을 짝지어 쉼표로 잇는 모양이다. 정해진 형식이 있어야 받는 쪽이 기계적으로 해석할 수 있다.
백엔드도 프론트엔드와 구조가 같다. 남이 만들어 둔 라이브러리를 pip으로 받아 내 코드와 합친다. npm과 같은 자리이고, 이름만 다르다.
요청 GET /api/posts?page=2
응답 {
"items": [
{ "id": 11, "title": "첫 글" },
{ "id": 12, "title": "둘째 글" }
],
"total": 57,
"page": 2,
"pageSize": 10
}API 설계는 세 가지를 정하는 일이다
API에도 설계라는 말이 붙는다. 정할 것이 셋 있기 때문이다.
첫째는 주소 규칙이다. 어떤 주소로 부르면 목록이고 어떤 주소면 하나의 상세인지를 정한다. 규칙이 있어야 다음 사람이 주소만 보고 무엇을 하는지 알 수 있다.
둘째는 동작의 구분이다. 사용자가 하는 일은 결국 만들기, 읽기, 고치기, 지우기 넷으로 정리된다. 앞 글자를 따 CRUD라고 부른다. 같은 주소라도 어떤 방식으로 요청했느냐로 이 넷을 가른다.
셋째는 응답의 모양이다. 이게 가장 자주 빠지는 항목이다. 목록을 준다면 항목만 담아서는 부족하다. 전체가 몇 개인지, 지금이 몇 쪽인지가 함께 있어야 화면에서 쪽 넘김을 그릴 수 있다. 로그인 응답, 오류 응답도 각각 모양을 정해 두어야 한다.
| 동작 | 요청 방식 | 주소 예시 |
|---|---|---|
| 목록 읽기 | GET | /api/posts |
| 하나 읽기 | GET | /api/posts/12 |
| 만들기 | POST | /api/posts |
| 고치기 | PUT · PATCH | /api/posts/12 |
| 지우기 | DELETE | /api/posts/12 |
에이전트에게 맡길 때 이 셋을 먼저 준다
이 셋을 정하는 이유는 원래 다른 개발자와 협업하기 위해서였다. 규칙이 있어야 남이 만든 API를 짐작으로 쓰지 않는다.
에이전트에게 맡길 때도 같은 이유로 값이 있다. 정해 주지 않으면 매번 다른 모양이 나온다. 어제는 목록에 total이 있었는데 오늘 만든 것에는 없고, 오류 응답 형식이 화면마다 다른 식이다. 그러면 화면 쪽 코드가 계속 흔들린다.
그래서 순서를 바꾼다. 코드를 만들어 달라고 하기 전에 주소 규칙, 동작 구분, 응답 모양 셋을 먼저 문서로 정해 준다. 그다음에 이 규격대로 만들어 달라고 한다.
이 셋만 앞에 두어도 뒤에 붙는 코드가 훨씬 덜 흔들린다. 다음 편에서는 이 백엔드가 값을 꺼내 오는 곳, 데이터베이스를 본다.