confluence-api

Confluence REST API

Confluence Cloud REST API v2를 한국어로 정리해 봤어요. v2는 기존 v1보다 응답 정의와 성능 면에서 개선된 레퍼런스예요. 페이지·블로그 글·스페이스를 만들고 읽고 수정하는 CRUD와 콘텐츠 검색, 인증 방법까지 폴링해서 코드 예시와 함께 설명드릴게요. 기본 URL은 https://<site>.atlassian.net/wiki/api/v2이고, HTTP 메서드와 JSON 요청/응답으로 동작해요.

출처: 문서

본문

인증과 권한 (Authentication and authorization)

Cloud 앱을 만드는 경우에는 JWT 또는 OAuth 2.0으로 인증해요. 반면 REST API에 직접 접근(직접 호출)할 때는 Basic auth를 지원해요.

  • Cloud 앱: JWT 또는 OAuth 2.0 사용
  • REST API 직접 호출: Basic auth 사용
  • 인가(Authorization): Cloud 앱은 scopes 또는 OAuth 2.0 user impersonation으로, 직접 호출 시에는 인증에 사용한 사용자(계정)를 기준으로 권한이 적용돼요.

Basic auth를 쓸 때는 API 토큰을 생성하고 계정 이메일을 사용자명으로 써요. 예를 들면 이렇게 해요.

curl -u "[email protected]:<API_TOKEN>" \
  https://your-domain.atlassian.net/wiki/api/v2/spaces

페이지네이션 (Pagination)

Confluence REST API v2는 커서 기반 페이지네이션(cursor-based pagination) 을 사용해요. 다중 객체를 반환하는 응답은 한 번에 일정 개수만 반환해서 응답 크기를 제한하고 서버 자원을 절약해요.

limit과 cursor 파라미터로 작업해요. 먼저 limit에 원하는 개수를 넣어 요청하고, 응답의 Link 헤더를 확인해요. 추가로 가져올 항목이 있으면 Link 헤더의 next URL로 다음 결과를 얻을 수 있어요. 이 상대 URL은 페이지네이션된 응답의 _links.next 속성에도 들어 있어요.

예를 들어 다음 요청은 대상 사이트에 5개 이상 페이지가 있다면 페이지 객체 5개를 반환해요.

GET /wiki/api/v2/pages?limit=5

추가 페이지가 더 있으면 Link 헤더는 이렇게 보여요.

</wiki/api/v2/pages?limit=5&cursor=<cursor token>>; rel="next"

Link 헤더 안의 URL로 다음 5개 페이지에 접근하고, rel="next"는 해당 URL이 "다음" 페이지 집합을 가리킨다는 뜻이에요. 단일 URL의 관계는 세미콜론(;)으로, URL 사이는 쉼표(,)로 구분해요. 더 이상 관련 URL이 없으면 Link 헤더도, 응답 본문의 _links에 next 속성도 나타나지 않아요.

페이지 (Page) CRUD

페이지 API는 페이지를 조회·생성·수정·삭제하는 기능이에요. 관련 scope는 읽기 read:page:confluence, 쓰기 write:page:confluence예요.

전체 페이지 조회

GET /wiki/api/v2/pages

페이지 목록은 limit으로 제한되고, 추가 결과가 있으면 Link 헤더의 next URL로 가져와요. 해당 사이트의 'Can use' 전역 권한이 필요하고, 사용자가 볼 권한이 있는 페이지만 반환돼요.

페이지 생성 (Create page)

스페이스에 페이지를 만들어요. 기본적으로 게시(published) 상태로 생성되고, status 필드에 draft로 지정하면 초안으로 만들 수 있어요. 게시 페이지를 만들려면 title이 필수예요. spaceId도 필수예요.

POST /wiki/api/v2/pages

요청 본문 예시는 이렇게 생겼어요.

{
  "spaceId": "<string>",
  "status": "current",
  "title": "<string>",
  "parentId": "<string>",
  "body": {
    "representation": "storage",
    "value": "<string>"
  },
  "subtype": "live"
}

페이지 단건 조회 (Get page by id)

GET /wiki/api/v2/pages/{id}

특정 페이지를 반환해요. 페이지와 해당 스페이스를 볼 수 있는 권한이 필요해요.

페이지 수정 (Update page)

PUT /wiki/api/v2/pages/{id}

페이지를 id로 수정해요. "current" 버전을 수정하면 제공된 본문 콘텐츠가 최신 버전으로 간주되고, 초안과의 콘텐츠 정합(reconciliation) 알고리즘을 통해 병합을 시도해요. 두 버전이 크게 달라지면 최신 콘텐츠가 초안을 완전히 덮어쓸 수도 있어요. id, status, title, body, version이 필수예요.

스페이스 내 페이지 조회 (Get pages in space)

GET /wiki/api/v2/spaces/{id}/pages

특정 스페이스의 모든 페이지를 반환해요. 사이트 'Can use' 전역 권한과 해당 스페이스 'View' 권한이 필요해요.

블로그 글 (Blog Post)

블로그 글은 read:blogpost:confluence(읽기)와 write:blogpost:confluence(쓰기) scope로 관리해요. 페이지처럼 목록 조회(GET /wiki/api/v2/blogposts)와 단건 조회(GET /wiki/api/v2/blogposts/{id}), 생성(POST /wiki/api/v2/blogposts), 수정(PUT /wiki/api/v2/blogposts/{id})이 가능하고, 동일하게 커서 기반 페이지네이션을 써요.

스페이스 (Space) CRUD

스페이스는 read:space:confluence(읽기)와 write:space:confluence(쓰기) scope로 관리해요.

전체 스페이스 조회

GET /wiki/api/v2/spaces

모든 스페이스를 반환하고, 결과는 id 오름차순으로 정렬돼요. limit으로 제한되고 추가 결과는 Link 헤더의 next로 가져와요. 사이트 'Can use' 전역 권한이 필요하고, 볼 수 있는 권한이 있는 스페이스만 반환돼요.

스페이스 생성 (Create space)

POST /wiki/api/v2/spaces

페이로드에 지정한 대로 스페이스를 만들어요. RBAC(Role-Based Access Control)가 활성화된 테넌트에서 사용할 수 있어요. name과 key가 필수예요.

{
  "name": "<string>",
  "key": "<string>",
  "alias": "<string>",
  "description": {
    "value": "<string>",
    "representation": "<string>"
  },
  "roleAssignments": [
    {
      "principal": {
        "principalType": "USER",
        "principalId": "<string>"
      },
      "roleId": "<string>"
    }
  ],
  "copySpaceAccessConfiguration": 64,
  "createPrivateSpace": true,
  "templateKey": "<string>"
}

스페이스 단건 조회 (Get space by id)

GET /wiki/api/v2/spaces/{id}

특정 스페이스를 반환해요. 스페이스를 볼 수 있는 권한이 필요해요.

콘텐츠 검색

v2의 페이지 API는 제목이나 id, space-id 등으로 필터링해서 찾을 수 있어요. 예를 들어 특정 제목의 페이지를 찾거나, 특정 스페이스의 페이지를 가져올 수 있어요.

GET /wiki/api/v2/pages?space-id=1234&limit=25

라벨로 페이지를 찾는 엔드포인트도 제공돼요.

GET /wiki/api/v2/labels/{id}/pages

지정한 라벨의 페이지를 반환하고, limit으로 개수를 제한하며 추가 결과는 Link 헤더의 next URL로 가져와요.

API 그룹 (더 많은 엔드포인트)

v2는 다음 API 그룹들을 제공해요. 필요할 때 공식 문서에서 각 그룹을 펼쳐서 확인해 보세요.

  • Admin Key, Attachment, App Properties, Ancestors
  • Blog Post, Children, Classification Level, Comment
  • Content, Content Properties, Custom Content, Database
  • Data Policies, Descendants, Folder, Label
  • Like, Operation, Page, Redactions
  • Smart Link, Space, Space Permissions, Space Properties
  • Space Roles, Task, User, Version, Whiteboard

각 문서 페이지 오른쪽 위의 미트볼 메뉴(⋮)에서 OpenAPI 스펙이나 Postman collection을 다운로드할 수 있어요.

더 알아보기 (Learn more)