API는 프로그램이 다른 기능을 사용하는 데 필요한 약속입니다. 라이브러리 함수도 API에 포함되며, 인터넷 주소가 반드시 필요한 것은 아닙니다. 여기서는 win-j의 글쓰기 화면이 도구 목록을 찾을 때 사용하는 HTTP API로 범위를 좁혀 요청과 응답의 계약을 읽어봅니다. MDN API 용어 설명
이 사이트의 도구 검색은 어떻게 연결되는가
글에 도구 링크를 넣을 때 관리자 화면은 검색어를 서버에 전달하고, 서버는 해당하는 도구 정보를 돌려줍니다. 현재 검색 경로는 /manager/utility-search-api/이며, 활성화된 staff 계정의 로그인이 필요합니다. 공개 방문자를 위한 무제한 검색 API로 제공되는 경로는 아닙니다.
아래는 2026년 9월 코드에서 확인한 요청 계약입니다.
| 항목 | 현재 동작 |
|---|---|
| 조회 요청 | GET /manager/utility-search-api/?q=글자수 |
| 입력 위치 | URL 쿼리의 q, 앞뒤 공백 제거 |
| 검색 필드 | 이름·설명·slug·검색 키워드 |
| 대상 조건 | visibility=public, is_active=True |
| 반환 개수 | 정렬된 결과 중 최대 20개 |
| 반환 구조 | 객체의 results 배열 |
| 각 결과의 필드 | name, description, url, icon, category |
이 관리용 검색의 대상 조건은 전체 사이트의 검색 색인 허용 여부를 판정하는 규칙과 같지 않습니다. 또한 현재 응답에는 총개수나 다음 페이지 정보가 없으므로 20개가 왔다고 해서 전체 도구가 20개라고 해석하면 안 됩니다.
응답 계약으로 화면 만들기
아래 JSON은 필드 구성을 설명하기 위해 만든 예시이며 실제 운영 검색 결과를 캡처한 것은 아닙니다.
{
"results": [
{
"name": "글자수 계산기",
"description": "텍스트 길이를 확인합니다.",
"url": "/utility/text-counter/",
"icon": "bi bi-tools",
"category": "텍스트"
}
]
}
화면은 배열을 순회해 이름과 설명을 표시하고 url을 링크로 사용합니다. 결과가 없을 때는 배열이 비어 있어야 하며, 화면은 “검색 결과 없음” 상태를 따로 보여주면 됩니다. 네트워크 오류나 로그인 만료까지 빈 배열로 처리하면 사용자는 검색어가 틀렸다고 오해할 수 있습니다.
관리자가 직접 확인하는 순서
- 본인이 관리하는 로컬 개발 사이트에서 staff 계정으로 로그인합니다.
- 개발자 도구 Network 탭을 열고 글쓰기 화면에서 도구 검색을 사용합니다.
- 요청 URL에 입력한
q가 들어갔는지 확인합니다. 한글은 URL에서 인코딩되어 보일 수 있습니다. - 응답이 200이고 JSON의
results가 배열인지 확인합니다. - 일치하지 않는 검색어도 넣어 빈 결과와 오류 상태를 구분합니다.
비로그인 상태에서는 이 경로가 401 JSON을 반환한다고 가정하면 안 됩니다. 현재 staff 보호 장치는 로그인 화면으로 302 이동시킵니다. 이를 자동으로 따라간 클라이언트는 HTML을 받아 JSON 해석에 실패할 수 있습니다. 상태와 이동 이력을 먼저 읽는 이유입니다.
조회와 저장 요청의 차이
같은 관리자 영역의 /manager/posts/write-v2/는 POST 폼 값을 읽어 글을 저장합니다. 검색은 조건을 URL에 전달하지만 저장은 제목·카테고리·본문 등을 요청 본문에 담습니다. 두 경로 모두 응답을 JSON으로 만들 수 있어도 요청 본문까지 JSON을 받는다는 뜻은 아닙니다.
현재 저장 코드는 Django의 request.POST를 사용합니다. 호출하는 쪽에서 마음대로 Content-Type: application/json으로 바꾸면 필드를 읽는 방식과 맞지 않습니다. 로그인 세션뿐 아니라 CSRF 검사도 통과해야 합니다. 이 차이는 HTTP 헤더와 본문 형식에서 구체적으로 다룹니다.
외부 API를 연결할 때 추가할 계약
이 사례는 같은 사이트 안의 관리자 기능이라 별도의 API Key가 없습니다. 외부 서비스는 제공자의 인증 방식, 사용 가능한 필드, 데이터 갱신 시점, 호출 제한, 비용, 오류 형식을 추가로 확인해야 합니다. API Key·OAuth·세션 중 어떤 방식인지는 문서에 따라 결정하며 API라는 이름만으로 추측하지 않습니다.
연동 전에 작은 표에 “요청 URL·메서드·인증·입력·성공 응답·빈 결과·실패 응답”을 적어두면 구현과 점검 기준이 분명해집니다. 실제 JSON을 받았을 때의 자료형 검사는 JSON 구조 확인, HTTP 자원 설계는 REST API 설계로 이어집니다.
첫 댓글을 남겨보세요.