공개 및 비공개 엔드포인트 노출하기
GraphQL은 전통적으로 https://mysite.com/graphql과 같은 단일 엔드포인트를 노출하는 것을 목적으로 합니다.
Gato GraphQL은 이 개념을 확장하여, 특정 요구에 맞게 커스터마이징된 여러 커스텀 엔드포인트를 노출할 수 있도록 합니다. 예를 들어, 다음과 같은 엔드포인트를 노출할 수 있습니다:
/internal과/public/apps/mobile과/apps/website/clients와/visitors/development,/staging,/production/teams/development,/teams/testing,/teams/marketing/clients/A,/clients/B,clients/Z- 이들의 임의 조합
Gato GraphQL은 퍼시스티드 쿼리도 지원합니다. 이는 GraphQL 쿼리가 미리 정의되어 서버에 저장된 엔드포인트입니다.
이 가이드는 각 엔드포인트를 어떻게, 언제 사용할지에 대한 제안을 소개합니다.
Gato GraphQL API 엔드포인트의 보안을 확보하는 것 외에도, WP Security Ninja와 같은 전용 보안 플러그인을 사용하여 WordPress 사이트의 보안을 항상 강화하시길 권장합니다.
단일 엔드포인트를 사용할 때
단일 엔드포인트는 항상 공개되어 있으며, 기본적으로 /graphql 하위에 노출됩니다.
Gato GraphQL은 "모듈"로 관리되며, 각 모듈은 GraphQL 스키마의 기능이나 확장을 제공하고, 필요에 따라 활성화 및 비활성화할 수 있습니다.
API의 보안을 강화하기 위해, 필요하지 않을 때는 GraphQL 스키마를 확장하는 모듈(예: "Posts", "Users", "Comments", "Blocks" 등)을 비활성화하는 것이 좋습니다. 이렇게 하면 해당 데이터가 처음부터 절대 노출되지 않도록 보장할 수 있습니다.
특히, API가 데이터를 변경(즉, 리소스 생성 또는 업데이트)하는 것을 목적으로 하지 않는다면, "Mutations" 모듈을 비활성화하는 것이 좋습니다. 그렇게 하면 뮤테이션을 제공하는 모든 확장("Post Mutations", "Comment Mutations" 등)도 비활성화되어, 이러한 뮤테이션이 GraphQL 스키마에서 절대 노출되지 않게 됩니다.
단일 엔드포인트는 다음의 경우에 권장됩니다:
- 단일 기능을 구동하기 위해 데이터를 가져와야 하고,
- WordPress 웹사이트가 공개 인터넷에서 접근할 수 없는 경우(즉, 개발용 노트북에서 실행 중이거나 방화벽 뒤에 있는 경우)
이는 예를 들어 헤드리스 사이트를 구축할 때(Next.js, Gatsby 등을 사용) 해당됩니다.
공개 커스텀 엔드포인트를 사용할 때
커스텀 엔드포인트는 단일 엔드포인트와 유사하지만, 여러 개를 가질 수 있으며, 각각이 자체 URL graphql/{custom-endpoint-slug}/ 하위에 노출되고, 각각 다른 설정을 가질 수 있습니다.
커스텀 엔드포인트는 모호성을 통한 보안을 제공합니다. 커스텀 엔드포인트의 존재와 URL을 알고 있는 것은 의도된 대상만이어야 하기 때문입니다.
API의 보안을 더욱 강화하기 위해, Access Control 확장 기능을 사용하여 다음의 경우에만 엔드포인트에 대한 접근을 허용할 수 있습니다:
- 사용자가 로그인한(또는 로그인하지 않은) 경우
- 사용자가 특정 역할을 가진 경우
- 사용자가 특정 권한을 가진 경우
- 방문자가 허용된 IP에서 접속하는 경우(Access Control: Visitor IP 확장 기능 사용)
각 커스텀 엔드포인트는 자체 액세스 컨트롤 목록을 가질 수 있으며, 특정 의도된 사용자만 접근할 수 있게 됩니다.
커스텀 엔드포인트는 다양한 애플리케이션, 팀, 클라이언트 또는 기타 사용자에 의한 API 접근을 관리하고 커스터마이징해야 할 때 권장됩니다.
비공개 커스텀 엔드포인트를 사용할 때
Gato GraphQL은 커스텀 엔드포인트를 커스텀 포스트 타입(CPT)으로 구현합니다. 이를 통해 커스텀 엔드포인트를 비공개로 게시할 수 있으며(또한 비밀번호 보호로도 가능), 커스텀 엔드포인트는 해당 커스텀 포스트에 접근 권한이 있는 로그인한 사용자만 접근할 수 있게 되고, 다른 누구도 접근할 수 없게 됩니다.
이 방법은 GraphQL 엔드포인트가 사이트 관리자만 사용하는 것을 목적으로 하는 경우(예: GraphQL을 사용하여 관리 작업을 수행할 때)에 권장됩니다. 외부 방문자가 엔드포인트에 접근하는 것을 완전히 차단함으로써, 사이트의 보안을 강화할 수 있습니다.
공개 퍼시스티드 쿼리를 사용할 때
퍼시스티드 쿼리는 각각 자체 URL을 가진 엔드포인트이지만, GraphQL 쿼리는 이미 서버 측에서 정의되어 있어 응답도 미리 정의되어 있습니다(URL 파라미터로 충족되는 변수를 정의하여 동적으로 만들 수 있습니다).
퍼시스티드 쿼리는 REST 엔드포인트와 유사하지만, GraphQL 언어를 사용하여 쿼리를 작성하고, wp-admin에서 직접 게시할 수 있습니다. 퍼시스티드 쿼리를 게시하기 위해 PHP 코드를 배포할 필요가 없습니다.
퍼시스티드 쿼리는 요청 본문에 GraphQL 쿼리를 전달할 필요가 없기 때문에, POST 대신 GET으로 접근하기에 자연스럽게 적합합니다.
(단일 엔드포인트와 커스텀 엔드포인트도 엔드포인트에 ?query={ GraphQL query } 파라미터를 추가하여 GET으로 접근할 수 있습니다.)
이를 활용하여 표준 HTTP 캐싱을 통해 API를 더 빠르게 만들고, 클라이언트 측 또는 클라이언트와 서버 사이의 중간 단계(예: CDN)에서 GraphQL 응답을 캐시할 수 있습니다.
이는 Cache Control 확장 기능을 통해 구현되며, 쿼리에 있는 필드와 디렉티브를 기반으로 응답의 max-age 값을 자동으로 계산하여 출력합니다.
퍼시스티드 쿼리는 가능한 한 항상 사용하는 것이 권장됩니다. 사이트의 보안을 크게 향상시키기 때문입니다.
이는 애플리케이션에서 사용 가능하게 해야 하는 모든 데이터를 퍼시스티드 쿼리를 통해 이미 노출할 수 있기 때문입니다. 그러면 GraphQL 단일 엔드포인트(또는 커스텀 엔드포인트)를 노출하는 것을 건너뛸 수 있어, 사용자가 (실수로든 그렇지 않든) 노출 상태로 남겨둔 비공개 데이터에 접근할 수 있는 가능성을 제거할 수 있습니다.
비공개 퍼시스티드 쿼리를 사용할 때
커스텀 엔드포인트와 마찬가지로, 퍼시스티드 쿼리는 CPT이므로 비공개(또는 비밀번호 보호)로 게시할 수 있어, 접근 권한이 있는 로그인한 사용자만 접근할 수 있게 되고, 다른 누구도 접근할 수 없게 됩니다.
WordPress 데이터를 직접 검색하는 경우와 같이 쿼리가 내부 용도로만 사용될 때마다 이를 사용하는 것이 권장됩니다.