API 레퍼런스

APost 공개 API를 사용하여 외부 웹사이트나 앱에서 발행된 콘텐츠를 가져올 수 있습니다.

개요

APost API는 REST 방식으로 동작합니다. 모든 요청은 https://apost.soviss.com/api/v1을 기준으로 합니다.

인증 (API Key)

모든 API 요청에는 API Key가 필요합니다.Authorization 헤더에 Bearer 토큰 형태로 전달합니다.

GET /api/v1/posts
Authorization: Bearer apost_sk_여러분의_API_KEY

Rate Limit

과도한 요청을 방지하기 위해 아래와 같은 제한이 적용됩니다:

제한 초과 시 429 Too Many Requests 응답이 반환됩니다. 응답 헤더의 X-RateLimit-Remaining으로 남은 횟수를 확인할 수 있습니다.

에러 형식

모든 에러는 동일한 JSON 형식으로 반환됩니다:

{
  "error": {
    "message": "에러 설명",
    "code": "ERROR_CODE",
    "status": 400
  }
}

GET /posts — 글 목록

발행된 글의 페이지네이션(쪽 나누기) 목록을 반환합니다.

엔드포인트

GET /api/v1/posts

쿼리 파라미터

응답 예시

{
  "data": [
    {
      "id": "uuid",
      "title": "블로그 SEO 완벽 가이드",
      "slug": "blog-seo-guide",
      "excerpt": "블로그 SEO의 핵심 전략을...",
      "locale": "ko",
      "word_count": 2500,
      "reading_time_min": 10,
      "published_at": "2026-03-10T09:00:00Z",
      "seo_title": "블로그 SEO 가이드 | 2026년",
      "seo_description": "초보자를 위한...",
      "seo_keywords": ["SEO", "블로그"],
      "category": { "id": "uuid", "name": "SEO" },
      "featured_image": {
        "id": "uuid",
        "cdn_url": "https://...",
        "alt_text": "SEO 가이드 대표 이미지",
        "width": 1200,
        "height": 630
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 45,
    "total_pages": 5
  }
}

GET /posts/{slug} — 단일 글

slug(주소 코드)로 단일 글의 전체 내용을 조회합니다.

엔드포인트

GET /api/v1/posts/{slug}

쿼리 파라미터

응답 필드

GET /categories — 카테고리 목록

사용자의 카테고리 목록을 반환합니다.

엔드포인트

GET /api/v1/categories

응답 예시

{
  "data": [
    {
      "id": "uuid",
      "name": "SEO",
      "description": "검색엔진최적화 관련 글",
      "parent_id": null,
      "sort_order": 0
    },
    {
      "id": "uuid",
      "name": "마케팅",
      "description": "디지털 마케팅 전략",
      "parent_id": null,
      "sort_order": 1
    }
  ]
}

GET /media/{path} — 이미지 프록시

발행된 글에 포함된 이미지를 외부 사이트에서 표시할 때 사용하는 프록시(중계) 엔드포인트입니다.

엔드포인트

GET /api/v1/media/{userId}/{date}/{filename}

사용 방법

외부 사이트에서 APost 이미지를 표시하려면, 웹 서버에 rewrite(경로 재작성) 규칙을 설정하세요.

# Next.js (next.config.js)
{
  source: '/img/:path*',
  destination: 'https://apost.soviss.com/api/v1/media/:path*'
}

# Nginx
location /img/ {
  proxy_pass https://apost.soviss.com/api/v1/media/;
  proxy_set_header Authorization "Bearer YOUR_API_KEY";
}

CORS 설정

모든 공개 API는 CORS(Cross-Origin Resource Sharing, 교차 출처 리소스 공유)가 활성화되어 있습니다. 브라우저에서 직접 호출할 수 있지만, API Key 노출에 주의하세요.

• 서버 측 호출 (권장): Next.js의 getServerSideProps, API Routes, 또는 백엔드에서 호출
• 클라이언트 호출: API Key를 환경 변수로 관리하고, 프록시를 통해 전달

활용 예시

Next.js에서 블로그 목록 페이지

// app/blog/page.tsx
async function getBlogPosts(page = 1) {
  const res = await fetch(
    `https://apost.soviss.com/api/v1/posts?page=${page}&per_page=10`,
    {
      headers: {
        Authorization: `Bearer ${process.env.APOST_API_KEY}`,
      },
      next: { revalidate: 60 }, // 1분 캐시
    }
  );
  return res.json();
}

export default async function BlogPage() {
  const { data: posts, pagination } = await getBlogPosts();

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>
          <a href={`/blog/${post.slug}`}>
            {post.title}
          </a>
        </li>
      ))}
    </ul>
  );
}

WordPress에서 REST API 연동

// functions.php
function get_apost_posts() {
  $response = wp_remote_get(
    'https://apost.soviss.com/api/v1/posts?per_page=5',
    [
      'headers' => [
        'Authorization' => 'Bearer ' . APOST_API_KEY,
      ],
    ]
  );

  if (is_wp_error($response)) return [];

  $body = json_decode(
    wp_remote_retrieve_body($response),
    true
  );

  return $body['data'] ?? [];
}

멀티 채널 — 채널별 글 분리 조회

하나의 계정에 여러 채널(사이트)을 연결한 경우, channel_id 파라미터로 특정 채널에 발행된 글만 가져올 수 있습니다.

// 사이트 A 채널의 글만 조회
const res = await fetch(
  `https://apost.soviss.com/api/v1/posts?channel_id=${CHANNEL_A_ID}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.APOST_API_KEY}`,
    },
    next: { revalidate: 60 },
  }
);

// 사이트 B 채널의 글만 조회
const resB = await fetch(
  `https://apost.soviss.com/api/v1/posts?channel_id=${CHANNEL_B_ID}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.APOST_API_KEY}`,
    },
  }
);