인스턴스 & 서버

이 페이지에서는 서버 메타데이터, 커스텀 이모지, 공지사항, 헬스 상태, 사용자 기본 설정, 프로필 디렉토리, oEmbed 임베드, 타임라인 마커 조회 API를 다룹니다.

인스턴스 정보

현재 인스턴스 (v2)

final instance = await client.instance.fetch();
print(instance.title);
print(instance.description);
print(instance.version);

설정된 언어, 규칙, 연락처 정보를 포함한 전체 v2 메타데이터를 담은 MastodonInstance를 반환합니다.

버전에 따라 달라지는 기능

새 Mastodon 릴리스에 추가된 기능을 제공하기 전에 detectCapabilities()로 지원 여부를 확인하세요.

final capabilities = await client.instance.detectCapabilities();

switch (capabilities.supportFor(MastodonCapability.collections)) {
  case MastodonCapabilitySupport.supported:
    // 컬렉션 기능을 제공합니다.
  case MastodonCapabilitySupport.unsupported:
    // 컬렉션 기능을 숨기거나 비활성화합니다.
  case MastodonCapabilitySupport.unknown:
    // 보수적인 대안을 사용하거나 사용자가 직접 시도하게 합니다.
}

Capability	서버 기능	최소 Mastodon 버전	API 기능 수준
tagFeaturing	태그를 프로필에 추천하거나 추천하지 않기	4.4.0	6
annualReportDetails	특정 연도의 연간 보고서 조회	4.4.0	6
oauthUserInfo	OpenID Connect 사용자 정보	4.4.0	6
asyncRefreshes	실험적 비동기 새로 고침 상태	4.4.0	6
quotePosts	인용 게시물 작업	4.5.0	7
collections	컬렉션 엔드포인트	4.6.0	10
donationCampaigns	기부 캠페인 엔드포인트	4.6.0	10
editableProfile	편집 가능한 프로필 조회 또는 수정	4.6.0	10
annualReportGeneration	보고서 생성 또는 상태 조회	4.6.0	10

감지는 다음 규칙을 따릅니다.

1. GET /api/v2/instance를 조회하고 api_versions.mastodon을 우선 사용합니다.
2. 이 필드가 없으면 MastodonInstance.version 앞부분의 major.minor.patch를 최선의 폴백으로 해석합니다.
3. v2 엔드포인트 자체가 404를 반환하면 레거시 GET /api/v1/instance를 조회하고 해당 버전 문자열을 사용합니다. 그 밖의 오류는 폴백하지 않고 그대로 전달합니다.
4. 메타데이터를 해석할 수 없으면 unknown을 반환합니다.

API를 호출할 때마다 인스턴스 메타데이터를 요청하지 말고 서버별로 앱 프로세스가 실행되는 동안 한 번 결과를 캐시하세요.

api_versions.mastodon은 릴리스 번호가 아닌 API 기능 수준을 나타냅니다. 패치 릴리스나 새 라우트가 없는 변경에서도 증가할 수 있고, 여러 릴리스가 같은 값을 공유하거나 정수를 건너뛸 수 있습니다. 표의 최소 임곗값으로만 사용하고 Mastodon 릴리스로 역변환하지 마세요.

기능 판정은 참고 정보입니다. 포크 및 호환 구현의 실제 기능은 보고된 메타데이터와 다를 수 있으므로 실제 API 호출 오류도 계속 처리해야 합니다. 특히 404 응답만으로는 엔드포인트가 없는 경우와 리소스가 없는 경우를 확실히 구분할 수 없습니다.

피어 도메인

final peers = await client.instance.fetchPeers();
// 알려진 연합 도메인 List<String>

주간 활동

final activity = await client.instance.fetchActivity();
for (final week in activity) {
  print('Statuses: ${week.statuses}');
}

최대 12주치 MastodonWeeklyActivity 객체를 반환합니다.

인스턴스 규칙

final rules = await client.instance.fetchRules();
for (final rule in rules) {
  print(rule.text);
}

도메인 차단 목록

final blocked = await client.instance.fetchDomainBlocks();

인스턴스가 차단한 도메인 목록을 반환합니다. 이것은 인스턴스 수준의 목록이며 사용자별 목록이 아닙니다. 사용자 수준의 도메인 차단은 모더레이션 페이지를 참고하세요.

확장 설명

final description = await client.instance.fetchExtendedDescription();
print(description.content);

개인정보 처리방침 및 서비스 약관

final policy = await client.instance.fetchPrivacyPolicy();
final tos = await client.instance.fetchTermsOfService();

// 날짜로 특정 과거 버전의 서비스 약관 조회
final old = await client.instance.fetchTermsOfServiceByDate('2024-01-01');

번역 언어

final languages = await client.instance.fetchTranslationLanguages();
// Map<String, List<String>> — 원본 언어 → 지원되는 대상 언어
languages.forEach((source, targets) {
  print('$source → $targets');
});

레거시 v1 (비권장)

// ignore: deprecated_member_use
final instanceV1 = await client.instance.fetchV1();

fetchV1()은 Mastodon 4.0.0부터 비권장되었습니다. 구버전 서버를 지원해야 하는 경우가 아니라면 fetch()를 사용하세요.

---

커스텀 이모지

final emojis = await client.customEmojis.fetch();
for (final emoji in emojis) {
  print(':${emoji.shortcode}: → ${emoji.url}');
}

인증이 필요하지 않습니다. 서버에서 사용 가능한 모든 커스텀 이모지의 List<MastodonCustomEmoji>를 반환합니다.

---

공지사항

공지사항 목록 조회

final announcements = await client.announcements.fetch();
for (final a in announcements) {
  print(a.text);
}

공지사항 읽음 처리

await client.announcements.dismiss('announcement-id');

인증된 사용자에게 공지사항을 읽음으로 표시합니다.

반응

// 반응 추가 (유니코드 이모지 또는 커스텀 단축코드)
await client.announcements.addReaction('announcement-id', '👍');
await client.announcements.addReaction('announcement-id', 'blobcat');

// 반응 제거
await client.announcements.removeReaction('announcement-id', '👍');

---

헬스 체크

final healthy = await client.health.check();
// 웹 프로세스, 데이터베이스, 캐시가 모두 정상이면 true를 반환합니다.
// 컴포넌트 중 하나라도 비정상이면 MastodonException이 발생합니다.

인증이 필요하지 않습니다. 모니터링 및 준비 상태 프로브에 유용합니다.

---

사용자 기본 설정

final prefs = await client.preferences.fetch();
print(prefs.postingDefaultVisibility);
print(prefs.postingDefaultLanguage);
print(prefs.expandSpoilers);

인증된 사용자의 MastodonPreferences를 반환합니다. 기본 설정을 업데이트하려면 client.accounts.updateCredentials()를 사용하세요.

---

프로필 디렉토리

// 가장 최근에 활동한 계정 (전체)
final active = await client.directory.fetch(
  order: 'active',
  limit: 40,
);

// 로컬 계정 중 최신 계정만
final newLocal = await client.directory.fetch(
  order: 'new',
  local: true,
);

파라미터:

파라미터	기본값	최대값	설명
limit	40	80	결과 수
offset	—	—	이 수만큼 결과 건너뜀
order	—	—	active 또는 new
local	—	—	true이면 로컬 계정만

인증이 필요하지 않습니다.

---

oEmbed

final embed = await client.oembed.fetch(
  'https://mastodon.social/@user/12345',
  maxwidth: 500,
);
print(embed.html);

포스트 URL의 임베드 가능한 HTML을 담은 MastodonOEmbed를 반환합니다. 인증이 필요하지 않습니다.

---

타임라인 마커

마커를 사용하면 세션과 기기 간에 홈 타임라인과 알림 타임라인에서 사용자의 읽은 위치를 유지할 수 있습니다.

마커 조회

final markers = await client.markers.fetch(['home', 'notifications']);
final home = markers['home'];
print(home?.lastReadId);

'home', 'notifications' 또는 둘 다 포함하는 목록을 전달합니다. 아무것도 지정하지 않으면 빈 맵을 반환합니다.

마커 저장

final updated = await client.markers.save(
  homeLastReadId: '109876543210',
  notificationsLastReadId: '987654321',
);

homeLastReadId 또는 notificationsLastReadId 중 하나 이상을 반드시 제공해야 합니다. 서버가 409 Conflict(다른 기기에서의 쓰기 충돌)로 응답하면 요청을 재시도하세요.

// 충돌 시 재시도 예시
Map<String, MastodonMarker> result;
while (true) {
  try {
    result = await client.markers.save(homeLastReadId: lastId);
    break;
  } on MastodonConflictException {
    // 재시도 전 짧은 대기
    await Future.delayed(const Duration(milliseconds: 500));
  }
}