WordPress REST API가 404를 반환하는 경우

이 오류의 의미와 확인 방법

• /wp-json/을 열면 REST API index JSON 대신 HTTP 404 페이지가 반환됩니다.
• JavaScript 애플리케이션, 모바일 앱, REST client, editor 또는 integration에서 WordPress API 요청에 대해 404 Not Found를 보고합니다.
• WordPress front end는 정상적으로 로드되지만 REST 요청은 실패합니다.
• /wp-json/의 보기 좋은 URL 경로는 404를 반환하는데 ?rest_route=/은 작동합니다.
• API index는 로드되지만 플러그인 또는 사용자 지정 endpoint가 404를 반환합니다.
• WordPress Site Health에서 REST API를 사용할 수 없다고 보고하지만, 원인을 확인하려면 response body와 status code를 확인해야 합니다.

가능성이 높은 순서의 주요 원인

1. 오래되었거나 누락된 permalink rewrite 규칙. migration, permalink 변경, 서버 변경 또는 불완전한 deployment 이후 흔히 발생합니다.
2. Web server 또는 proxy가 /wp-json/을 WordPress로 전달하지 않음. Apache rewrite 지원, Nginx try_files 라우팅, document-root 매핑 또는 virtual-host 설정이 잘못되었을 수 있습니다.
3. 보안, firewall, CDN, cache 또는 hosting 규칙이 404를 반환함. 일부 제어 기능은 차단된 요청에 forbidden 대신 not found를 반환하여 요청을 숨깁니다.
4. 플러그인 또는 theme이 REST 동작을 변경함. route를 제거하거나, 접근을 제한하거나, REST response를 필터링할 수 있습니다.
5. 사용자 지정 또는 플러그인 endpoint 하나만 잘못됨. namespace, route, version, HTTP method 또는 resource ID가 잘못되었거나 route가 등록되지 않았을 수 있습니다.
6. 요청이 잘못된 설치 경로 또는 사이트를 대상으로 함. domain 변경, subdirectory 설치, redirect, 오래된 application 설정 및 cache된 response로 인해 client가 오래된 API base path를 사용할 수 있습니다.

해결 방법

1. 404의 범위와 발생 위치 확인

정확한 요청 경로, HTTP status, response body, response headers, request method 및 timestamp를 기록하세요. response가 WordPress, web server, reverse proxy, CDN 또는 보안 계층 중 어디에서 발생했는지 확인하세요. 진단 기록에 access token, cookie, password 또는 비공개 response 데이터를 포함하지 마세요.

적절한 client에서 /wp-json/의 REST API index를 테스트하세요. index가 JSON을 반환하지만 endpoint 하나가 404를 반환한다면 바로 5단계로 이동하세요. index 자체가 404를 반환한다면 계속 진행하세요.

2. WordPress rewrite 규칙 새로 고침

WordPress dashboard에서 Settings → Permalinks를 열고 선택된 permalink 구조를 변경하지 않은 채 Save Changes를 클릭하세요. 이 작업은 WordPress의 rewrite 설정을 새로 고칩니다.

다시 /wp-json/을 테스트하세요. deployment automation 또는 hosting control panel에서 서버 설정을 관리한다면 rewrite 설정이 저장되며 다음 deployment에서 덮어쓰이지 않는지 확인하세요.

3. 보기 좋은 경로와 fallback route 비교

WordPress의 query-parameter fallback을 사용해 REST API를 테스트하세요. 사이트의 일반적인 home address 뒤에 ?rest_route=/을 추가합니다. 실제 scheme, hostname 및 설치 경로를 사용하세요. subdirectory 설치에서는 해당 경로가 요청의 일부로 유지되어야 할 수 있습니다.

• Fallback은 작동하지만 /wp-json/은 실패: WordPress가 REST 요청을 처리할 수 있으므로 보기 좋은 URL의 rewrite, virtual-host 설정, proxy 라우팅, document-root 매핑 및 migration 변경을 조사하세요.
• 둘 다 실패: 보안 제어 기능, 서버 front controller 라우팅, WordPress 및 플러그인 동작, 설정된 사이트 또는 설치 경로를 점검하세요.
• 두 index 요청은 모두 작동하지만 사용자 지정 route 하나가 실패: 5단계에서 해당 endpoint를 구체적으로 진단하세요.

4. Web server, proxy 및 보안 라우팅 확인

Apache의 경우 권한이 있는 관리자에게 WordPress 디렉터리에서 rewrite 지원이 활성화되어 있는지, 사이트의 rewrite 규칙이 virtual-host 설정에 존재하고 허용되는지 확인하도록 요청하세요. Nginx 또는 reverse proxy의 경우 요청이 WordPress front controller에 도달하는지, /wp-json/이 존재하지 않는 정적 파일로 처리되지 않는지 확인하세요.

다음 순서로 관련 기록을 검토하세요.

1. 실패한 요청에 대한 web server access 및 error log.
2. CDN, load balancer 및 reverse proxy의 규칙과 cache entry.
3. WordPress 보안, firewall, login protection 및 REST 제어 플러그인.
4. 경로, method 또는 request header를 차단된 것으로 분류할 수 있는 hosting 수준의 WAF 규칙.

한 번에 하나의 통제된 변경만 수행하고, 원래 설정을 기록하며, 권한을 확인한 후 관련 cache만 purge하세요. 승인된 maintenance plan 없이 production firewall 또는 보안 플러그인을 광범위하게 비활성화하지 마세요. 보안 규칙이 원인이라면 모든 보호 기능을 우회하지 말고 필요한 REST 경로와 method만 좁게 허용하세요.

5. 누락된 endpoint 하나 진단

endpoint의 정확한 namespace, route, version segment, HTTP method, trailing path 및 resource identifier를 확인하세요. 요청을 플러그인 또는 애플리케이션이 제공한 route 문서나 등록 코드와 비교하세요.

다음 사항을 확인하세요.

• 테스트 중인 환경에서 해당 플러그인 또는 theme이 활성화되어 있습니다.
• REST initialization 중 route 등록이 실행됩니다.
• route에 예상된 permission callback이 있으며 현재 요청에 대해 조건부로 제외되지 않습니다.
• client가 오래된 domain, subdirectory 또는 cache된 application 설정이 아니라 현재 사이트의 API base path를 사용합니다.
• 요청한 resource가 실제로 존재합니다. 누락된 post, user, product 또는 기타 resource는 REST API가 정상이어도 endpoint 수준에서 정당한 404를 반환할 수 있습니다.

가능한 경우 API index 또는 route-discovery response를 확인하세요. 예상한 route가 없다면 문제를 일반적인 REST outage로 간주하기보다 등록 상태, 플러그인 상태, namespace 및 환경별 설정을 조사하세요.

6. 통제된 변경 후마다 재확인

browser, 권한이 있는 API client, 그리고 해당되는 경우 오류를 보고한 application에서 다시 테스트하세요. 각 변경 전후의 status code, response headers, response body 및 response origin을 비교하세요. 임시 진단 변경 사항을 되돌리고 최종 rewrite, firewall, cache, proxy 또는 플러그인 설정을 문서화하세요.

예방 및 해결 확인 방법

• migration 및 deployment 점검에 /wp-json/과 업무상 중요한 각 사용자 지정 route를 대상으로 한 REST API smoke test를 추가하세요.
• 환경 간 WordPress site URL, home URL, document root 및 subdirectory 설정을 일관되게 유지하세요.
• rewrite 설정, proxy 규칙, firewall 정책 및 cache 동작을 문서화된 deployment 설정으로 관리하고, 문서화되지 않은 서버 변경으로 남겨 두지 마세요.
• 보안 플러그인 및 WAF 변경 사항이 인증된 REST 요청과 인증되지 않은 REST 요청 모두에 미치는 영향을 검토하세요.
• 중요한 API 호출의 response status와 response origin을 모니터링하여 proxy가 생성한 404와 WordPress가 생성한 404를 구분할 수 있도록 하세요.
• 각 endpoint를 담당하는 사용자 지정 namespace, route, 지원 method, permission 동작 및 플러그인 또는 theme을 문서화하세요.