TL;DR

  • Instapaper가 수백만 사용자가 이용하는 통합 기능을 위한 API v2를 공개하고, OAuth 2·베어러 토큰·RESTful 설계를 적용함.
  • API v2는 JSON 요청 본문, 표준 HTTP 상태 코드, 제한 없는 북마크 페이지네이션, 동기화용 since 매개변수, 태그 엔드포인트를 제공함.
  • 자체 계정용 개인 액세스 토큰을 몇 단계로 생성할 수 있으며, 다른 사용자를 위한 앱은 OAuth 2 인증 코드 흐름을 사용함.
  • 모든 엔드포인트를 지원하는 Python·TypeScript SDK와 클라이언트 생성 등에 활용 가능한 OpenAPI 명세를 공개함.
  • API v1 통합은 장기 지원 상태로 계속 작동하며, xAuth는 2027년 9월 30일 종료 예정이고 기존 토큰은 API v2 베어러 토큰으로 사용할 수 있음.

API v2 공개

  • Instapaper가 최신 표준인 OAuth 2, 베어러 토큰, RESTful 설계 등을 기반으로 한 새 API인 Instapaper API v2를 공개함.
  • Python 및 TypeScript용 퍼스트파티 SDK와 새 API의 OpenAPI 명세도 함께 공개함.
  • API v1은 2011년에 공개됐으며, 이후 개발자들이 수천 개의 통합 기능을 구축했고 이 기능들은 수백만 Instapaper 사용자들이 이용함.
  • API v1은 OAuth 1.0a 요청 서명 방식이 번거롭고, xAuth 사용 시 앱이 사용자의 Instapaper 비밀번호를 수집해야 하며, URL 인코딩 문자열 같은 덜 일반적인 출력 형식도 지원함.
  • API v1에서는 거의 모든 오류가 HTTP 400으로 반환됐으며, API v2가 이러한 문제를 해결함.

새로운 기능

  • OAuth 2: OAuth 1.0a 요청 서명을 없애고 모든 요청을 단일 Authorization: Bearer 헤더로 인증함. 사용자는 Instapaper의 동의 페이지에서 로그인하고 앱 사용을 승인하므로 앱이 비밀번호를 확인하지 않음. 자세한 내용은 인증 안내에서 확인할 수 있음.
  • 개인 액세스 토큰: 자신의 계정으로 API를 사용하려는 경우 OAuth 흐름을 구현하지 않고 몇 번의 클릭으로 액세스 토큰을 생성할 수 있음.
  • RESTful 설계: 요청에 JSON 본문을 사용하고, 리소스 경로와 표준 HTTP 메서드를 적용하며, 오류를 읽기 쉬운 메시지와 실제 HTTP 상태 코드로 반환함.
  • 페이지네이션 및 동기화 개선: API v1의 페이지네이션 제한과 동기화용 사용자 정의 have 매개변수 대신, API v2 북마크 엔드포인트가 계정 전체에 접근할 수 있도록 페이지네이션 제한을 없애고 마지막 동기화 이후의 모든 변경 사항을 제공하는 since 매개변수를 사용함.
  • 태그: 태그 나열, 생성, 편집을 위한 엔드포인트를 제공함.

자체 계정에서 API 사용

  • 개인 스크립트, 자동화, 도구에서 Instapaper API를 사용하는 경우, 기존에는 자신의 글에 접근하기 위해서도 OAuth 1.0a와 xAuth를 구현해야 했음.
  • 이제 instapaper.com/developers/applications에서 다음 순서로 개인 액세스 토큰을 생성할 수 있음.
  • 애플리케이션을 선택하거나 새 애플리케이션을 생성함.
  • ‘Generate access token’을 클릭함.
  • 토큰을 사용해 https://www.instapaper.com/api/2/bookmarks로 요청을 보낼 수 있음. 요청에는 Authorization: Bearer YOUR_ACCESS_TOKEN 헤더를 포함함.
  • 토큰은 한 번만 표시되며, 같은 페이지에서 언제든 재생성하거나 취소할 수 있음.
  • 다른 사용자를 위한 앱을 만드는 경우에는 인증 안내에 문서화된 전체 OAuth 2 인증 코드 흐름을 사용함.

Python 및 TypeScript SDK

  • Instapaper가 Python 및 JavaScript/TypeScript용 오픈소스 클라이언트 라이브러리를 공개함.
  • 두 SDK 모두 API v2의 모든 엔드포인트를 지원하고, 페이지 이동과 동기화를 처리하며, API 오류를 형식이 지정된 예외로 변환하고, OAuth 2 흐름용 도우미를 포함함.
  • 두 SDK 모두 런타임 의존성이 없음.
  • Python 패키지: instapaper-api; 저장소: instapaper-api-python.
  • JavaScript/TypeScript 패키지: instapaper-api; 저장소: instapaper-api-js.
  • Python에서는 pip install instapaper-api로 설치하고, 액세스 토큰으로 Instapaper 클라이언트를 생성해 사용자 정보 조회, 북마크 저장 및 보관, 보관함 목록 조회를 수행할 수 있음.
  • 다른 사용자를 대신해 작업할 때는 Python SDK의 OAuth 도우미에 클라이언트 ID, 클라이언트 시크릿, 리디렉션 URI를 지정하고, 상태값을 생성해 인증 URL로 사용자를 보냄. 콜백에서 상태값을 확인한 뒤 인증 코드를 토큰으로 교환해 클라이언트를 생성함.
  • TypeScript에서는 npm install instapaper-api로 설치하고, 액세스 토큰으로 클라이언트를 생성해 사용자 정보 조회, 북마크 저장 및 보관, 보관함 목록 조회를 수행할 수 있음.
  • TypeScript SDK는 Node 18 이상, Bun, Deno 및 fetch를 제공하는 엣지 런타임에서 실행됨. 각 저장소의 README에 전체 메서드가 안내돼 있음.

OpenAPI 명세

  • API v2의 전체 OpenAPI 명세는 instapaper.com/api/2/openapi.json에서 확인할 수 있음.
  • 명세를 이용해 원하는 언어의 클라이언트를 생성하고, Postman 같은 도구로 API를 가져오거나, 코딩 에이전트에 Instapaper 기반 개발에 필요한 정보를 제공할 수 있음.

API v1 관련 안내

  • API v1은 장기 지원 상태이며 기존 통합 기능은 계속 작동함.
  • xAuth는 더 이상 사용하지 않을 예정임. xAuth는 앱이 사용자의 이메일과 비밀번호를 수집해 Instapaper로 보내도록 요구하며, 이는 현대 보안 모범 사례를 따르지 않음. 신규 애플리케이션은 API v2와 OAuth 2를 사용해야 함.
  • 2027년 9월 30일에 xAuth를 종료할 예정이며, 이후 신규 사용자는 xAuth로 로그인할 수 없음.
  • API v1 통합 기능의 마이그레이션은 다음과 같이 진행할 수 있음.
  • 재등록 불필요: 기존 소비자 키와 시크릿을 API v2의 client_id와 client_secret으로 사용함. 애플리케이션의 콜백 URI에 리디렉션 URI를 추가해야 함.
  • 재인증 불필요: 앱이 이미 보유한 액세스 토큰은 API v2 베어러 토큰으로 작동하므로 기존 사용자는 다시 로그인할 필요가 없음.
  • 엔드포인트 대응표: 마이그레이션 안내에서 모든 v1 엔드포인트에 대응하는 v2 엔드포인트를 확인할 수 있음.

시작하기

  • API v2 문서에서 첫 요청에 필요한 내용을 확인할 수 있으며, API 참조 문서에서 모든 엔드포인트를 확인할 수 있음.
  • 문의, 피드백, 진행 중인 작업 공유는 support@instapaper.com으로 보낼 수 있음.