엔드포인트

기본 정보

시작하기

규칙

모든 API 요청을 전송하는 기본 URL은 https://picple.com입니다. 모든 API 요청에는 HTTPS가 필요합니다.

Notion API는 페이지와 데이터베이스 리소스에 대한 GET, POST, PATCH, DELETE 요청을 통해 대부분 작업을 수행하는 등 가능한 한 RESTful 규칙을 따릅니다. 요청과 응답 본문은 JSON으로 인코딩됩니다.

JSON 규칙

최상위 리소스에는 "object" 속성이 있습니다. 이 속성은 리소스의 유형을 결정하는 데 사용할 수 있습니다(예: ”database", "user" 등).
최상위 리소스는 UUIDv4 "id" 속성으로 주소를 지정할 수 있습니다. Notion URL에서 ID를 복사할 때와 같이 API에 요청할 때 ID에서 대시를 생략할 수 있습니다.
속성 이름은 Camel Case나 Kebab Case가 아닌 Snake Case로 되어 있습니다.

페이지네이션

요청 제한

모든 API 사용자에게 공평한 경험을 보장하기 위해 Notion API는 요청 속도 제한이 적용되며 요청 파라미터에 사이즈 제한이 적용됩니다.

속도 제한

속도가 제한된 요청은 "rate_limited" 오류 코드(HTTP 응답 상태 429)를 반환합니다. 통합당 요청에 대한 속도 제한은 초당 평균 3건입니다. 평균 속도를 초과하는 일부 버스트는 허용됩니다.

<aside> ❗ 속도 제한은 변경될 수 있습니다.

앞으로는 수요와 안정성의 균형을 맞추기 위해 전송률 한도를 조정할 계획입니다. 또한 요금제에 따라 워크스페이스에 별도의 속도 제한이 도입될 수 있습니다.

</aside>

사이즈 제한

Notion은 요청 시 특정 파라미터의 크기와 children의 깊이를 제한합니다. 이러한 제한을 초과하는 요청은 "validation_error" 오류 코드(HTTP 응답 상태 400)를 반환합니다. 더 구체적인 세부 정보는 "message" 속성에서 확인할 수 있습니다.

속성값 유형	내부 속성	사이즈 제한
서식 있는 텍스트 객체	`text.content`	2,000자
서식 있는 텍스트 객체	`text.link.url`	2,000자
서식 있는 텍스트 객체	`equation.expression`	1,000자
모든 서식 있는 텍스트 객체 배열		100개

상태 코드

HTTP 응답 코드는 일반적인 성공과 오류 클래스를 나타내는 데 사용됩니다.

성공 코드

HTTP 상태	설명
200	성공적으로 처리된 요청

오류 코드

오류 응답 본문의 “code"와 "message" 속성에서 오류에 대한 더 구체적인 세부 정보를 확인할 수 있습니다.

HTTP 상태명	`code`	`message`
400	invalid_json	The request body could not be decoded as JSON
	invalid_request_url	This request URL is not valid.
	invalid_request	This request is not supported.
401	unauthorized	The bearer token is not valid.

객체

사용자

사용자 객체가 API에 나타나는 위치

사용자 객체는 다음을 포함해 API에서 반환되는 거의 모든 객체에 표시됩니다.

생성자, 최종 편집자 속성의 블록 객체
생성자, 최종 편집자 , 사람 속성의 페이지 객체
생성자, 최종 편집자 속성의 데이터베이스 객체
사용자가 멘션 시 서식 있는 텍스트 객체
사람 속성에서 속성 객체

사용자 객에는 아래 설명된 대로 object와 id 키가 항상 포함됩니다. 사용자가 서식 있는 텍스트나 페이지 속성 컨텍스트에서 렌더링되고, 봇이 해당 속성에 액세스할 수 있는 올바른 기능이 있는 경우 나머지 속성이 표시될 수 있습니다. 기능에 대한 자세한 내용은 기능 가이드와 인증 가이드를 참고하세요.

모든 사용자

이 필드는 사람과 봇을 포함한 모든 사용자에 적용됩니다. *이 표시된 필드는 항상 존재하는 속성입니다.

속성	업데이트 가능	유형	설명	예시 값
`object`*	디스플레이 전용	`"user"`	항상 ‘user’	`"user"`
`id`*	디스플레이 전용	`string`(UUID)	사용자의 고유 식별자	`"e79a0b74-3aba-4149-9f74-0bb5791a6ee6"`
`type`	디스플레이 전용	`string`(선택 사항, 열거형)	‘방장’이나 ‘초대자’같은 사용자 유형	`"chief"`, `“partic”`
`Nickname`	디스플레이 전용	`string`	Notion에 표시되는 사용자 이름	`"Avocado Lovelace"`

방 정보

이 필드는 picple로 표현됩니다. 방 정보의 경우 방장의 토큰 정보, 초대 코드, 생성 일자, 인증 번호가 들어 있을 예정입니다.

<aside> 💡 Redis, Kafka, DB 중 선택적으로 정보를 담으면 좋을 것 같습니다.

</aside>

{
  "type": "chief",
  "picple": {
    "chief_token": "선택된 방식에 따라 변경",
	    "invited_code": "8자리 코대코드를 넣으면 될 듯",
    "create_as": "2022-10-24T22:49:22.765Z"
  }
}

각 파일 객체에서 다음 필드를 확인할 수 있습니다.

필드	속성	설명	예시 값
`chief_token`	`string`
`varchar`	방을 생성한 방장의 토큰 번호로 방을 폭파할 수 있는 권한을 위해 넣어주는 것이 좋을 것 같습니다.	`"ansdliufh139!#dlkfjei@jldkfjlkfj&kfgjlk"`
`invited_code`	`string`	외부 연결에서 서버를 통해 입력하기 위한 초대코드입니다.	`“134fej4u”`
`create_as`	`DATE`	방이 생성된 날짜를 저장하는 필드입니다. 방이 생성된 시간에 따라 처리하기 위해서는 필요하다고 생각합니다.	`“2024-07-12 14:09:25”`

참고용

API 명세서