ネオアスタルテAPIドキュメント
アドベントカレンダー２５日目
はじめまして、アスタルテのサバ缶をしています。
新規ユーザーの霧島ひなたと申します。
今年は、たぶん動くと思うからリリースしようぜ！
をモットーに様々なゴミプロダクトをリリースしてきました。
めかむし、クライアント、問題を説く奴、ブログ…
そして、とうとうmastodonってめちゃくちゃ重たいし、
最近のFediverseは治安悪すぎる！！！！(えっちぃ画像とか変な人とかすごい増えた・・・)
ということで
RustでSNS作るぞい！
の有言実行を始めました。
今までこんな仕様のSNSがあればいいのにと思ってきたすべてを形にしていきたいですね！！！
まぁそんなこんなで今回は、今日までに実装されている
ネオアスタルテのAPIのドキュメントをサクッと書いていきたいと思います。
基本事項
現在、(仮称)ネオアスタルテはテスト中という扱いであり正式サービスを開始しているわけではありません。
したがってここで書かれているドキュメントの内容は正式サービス開始時、あるいは、開発過程で変更になる可能性があります。
正式サービス開始後はAPIの使用変更に伴い、開発者の対応が必須となる変更が行われる時には必ず事前にアナウンスを行い、
対応するのに必要十分な時間を確保したうえでAPIの変更を行いますが、
テストサーバーに関しては、そのような配慮は行われません。ご容赦ください。
エンドポイントは
/api/・・・
と記載しますが
テストサーバーに接続する場合は
https://test.neo.astarte.krsm.me/api/・・・
であることに注意してください。
正式サービス後はドメインを変更する必要があります。
{url}/api/・・・
など変数を用いた切り替え可能な実装をするなどの対応をしてください。
APIについての基本事項
ネオアスタルテは基本的には REST API に準拠した実装になっていますが、一部例外もあります。
開発の都合上 レスポンス200 が返ってきていてもエラーの場合があります。
正式サービスまでには正しいレスポンスが返ってくるようになります。
ネオアスタルテのAPIは get リクエストを除くそのほかすべてのリクエストで原則 Body に
Content-Type : application/json
でパラメータを乗せる必要があります。
URL上にパラメータが乗る query をネオアスタルテは解析しません。
ドキュメント上に但し書きがない場合、
パラメータ: Body
ヘッダー: Header
にそれぞれ情報を載せたうえでリクエストしてください。
パラメータには必須のものとオプションのものがあります。また必須、オプション問わず、型厳密であり、設定されたパラメータの型が一致しない場合エラーとなります。
次のような例に十分注意して下さい。
integer: 必須 int型
の場合正しく解析されるには
{
integer: 23
}
である必要があります。
{
integer: "23"
}
は型変換可能な形ではありますが、エラーを返します。
ネオアスタルテが返すエラーはライブラリで処理されるものと実装されたものがあり、ライブラリで処理されるエラーを除く、そのほかは、標準エラー型として定義されています。
標準エラー型は以下のような形式をとっています。
例はユーザー登録をしようとした時、パラメータに使用できない文字列が含まれていた場合のレスポンスです。
{
message: "usernameには、大文字小文字のアルファベットと数字、ひらがな、カタガナ、漢字のみが利用できます。"
}
messageの項になぜエラーレスポンスとなったのかが日本語で記載されて変換されます。
これはユーザーにも十分理解可能な内容となっており、直接ユーザーにメッセージとして出力することも可能です。
ライブラリが返すエラーと特殊な場合を除き、そのほかは標準エラー型が返還されるためこのドキュメントでは特殊なエラーレスポンスが返る場合を除きエラーレスポンスに関する記述を省略します。
特に記載がない場合
パラメータの記載方法
名称 : 必要性 データ型 [パラメータの条件、備考]
または
名称 : 必要性 データ型 "この値でリクエストすること"
ヘッダーの記載方法
認証タイプ
Basic または Bearer
名前: 必要性
レスポンスの記載方法
名称 : データ型 [備考]
または
名称 : データ型 "必ずその値が返ってくる"
データ型が
<String型>
など<>で囲まれている場合、その項目はnullが返却される可能性があることに注意してください。
データ型にはよく使われるデータ型があり
{account_data型}
{client_owner_data型}
があります。
各データ型は以下の構造をとります。
account_data型
{
id: String型,
username: String型,
display_name: <String型>,
bio: <String型>,
icon_url: String型,
header_url: <String型>
}
client_owner_data型
{
client_name: String型,
client_id: String型,
owner_account: {account_data型},
website: String型,
}
ユーザー登録
エンドポイント
api/user/create_account
リクエストタイプ
POST
パラメータ
{
username: 必須 String型 [3-32文字、ひらがな、カタガナ、漢字、大文字小文字英数字、アンダーバー],
password: 必須 String型 [8文字以上],
email: 必須 String型,
}
レスポンス
{
username: String型[登録したusername],
message: "アカウントの作成が完了しました",
}
エラーレスポンス：標準エラー型
メールアドレス認証
エンドポイント
api/user/email_verify
リクエストタイプ
POST
パラメータ
{
user_id: 必須 String型 [メールアドレスに記載してる物を入力してください],
code: 必須 String型 [メールアドレスに記載してる物を入力してください],
}
レスポンス
{
message: "アカウントの認証が完了しました"
}
エラーレスポンス：標準エラー型
パスワードリセットリクエスト
エンドポイント
api/user/password_reset_request
リクエストタイプ
POST
パラメータ
{
user_id: 必須 String型 自分に割り振られたユニークなID(最初にメールで送られてきてるもの),
email: 必須 String型 登録したメールアドレス,
}
レスポンス
{
message: "リセット用の情報が書かれたメールを送信しました"
}
メールアドレスにパスワードリセットに必要な情報が送られます。
エラーレスポンス：標準エラー型
パスワードリセット
エンドポイント
api/user/password_reset
リクエストタイプ
POST
パラメータ
{
user_id: 必須 String型 自分に割り振られたユニークなID(最初にメールで送られてきてるもの),
email: 必須 String型 登録したメールアドレス,
code: 必須 String型 メールアドレスに送られているコード,
new_password: 必須 String型 新しいパスワード(8文字以上),
retype_new_password: 必須 String型 新しいパスワード(8文字以上),
}
レスポンス
{
message: "パスワードの変更が完了しました。"
}
エラーレスポンス：標準エラー型
トークンの発行
エンドポイント
api/user/get_token
リクエストタイプ
POST
認証タイプ
Basic
サンプル
Basic (Base64エンコードした username:password)
ヘッダー
Authorization: 必須
パラメータ
{
grant_type: 必須 "password",
client_id: 必須 String型,
client_secret: 必須 String型,
}
レスポンス
{
access_token: String型,
token_type: String型 "Bearer",
}
エラーレスポンス：標準エラー型
プロフィール取得
エンドポイント
api/user/profile
リクエストタイプ
GET
認証タイプ
Bearer
ヘッダー
Authorization: 必須
パラメータ
{
id: オプション String型
}
レスポンス
{
id: String型,
username: String型,
display_name: <String型>,
bio: <String型>,
icon_url: String型,
header_url: <String型>,
spoints: Int型 [トークンの所有者以外のプロフィール取得時はなし]
}
エラーレスポンス：標準エラー型
プロフィール変更
エンドポイント
api/user/profile
リクエストタイプ
PATCH
認証タイプ
Bearer
ヘッダー
Authorization: 必須
パラメータ
{
display_name: オプション String型,
bio: オプション String型,
icon_url: オプション String型 [制限付き],
header_url: オプション String型 [制限付き],
}
レスポンス
{
id: String型,
username: String型,
display_name: <String型>,
bio: <String型>,
icon_url: String型,
header_url: <String型>,
spoints: Int型,
secret_word: Option<String>,
follow_limit: String,
follow_message: bool
}
エラーレスポンス：標準エラー型
制限:
この項目では直接URLを指定しますが現在はアスタルテに投稿された画像のみが許可されています。
fastlyのURLのみを解析します。
jpg jpeg png gif を受け付けています。
フォロー関係の制限
エンドポイント
api/user/follow_setting
リクエストタイプ
PATCH
認証タイプ
Bearer
ヘッダー
Authorization: 必須
パラメータ
{
secret_word: Option<String>,
follow_limit: Option<String>,
follow_message: Option<bool>
}
レスポンス
{
id: String型,
username: String型,
display_name: <String型>,
bio: <String型>,
icon_url: String型,
header_url: <String型>,
spoints: Int型
secret_word: Option<String>,
follow_limit: String,
follow_message: bool
}
エラーレスポンス：標準エラー型
制限: 合言葉(ssecret_word)は8文字以下でしか設定することは出来ません。
一度に複数の情報を取得する事が出来ます。
投稿したすべての情報が正常に更新出来た場合、新しく設定したプロフィール情報がレスポンスとして帰ってきます。
問題が発生した場合標準エラー型を利用して、どこに問題があったか通知されます。
follow_limitについてフォローリミットはString型で0-4までの数字を入力する必要があります。
5と6については管理者の許可を得たユーザーのみが使用できる特殊な制限です
0 すべてのフォローを通す
1 すべてのフォローを弾く
2 すべてのフォローをフォローリクエストとして処理する
3 合言葉認証を行う。通った場合は、フォローを通す。通らなかった場合は、フォローリクエストとして処理する
4 合言葉認証を行う。通った場合は、フォローを通す。通らなかった場合は、フォローを弾く
5 合言葉認証を行う。通った場合は、フォローリクエストとして処理する
6 すべてのフォローを闇の中に消し去る。(フォローできたように見せかけて、フォローできないｗ)
フォロー
エンドポイント
api/user/follow
リクエストタイプ
POST
認証タイプ
Bearer
ヘッダー
Authorization: 必須
パラメータ
{
user_id: String,
secret_word: Option<String>,
message: Option<String>
}
レスポンス：標準エラー型
エラーレスポンス：標準エラー型
ネオアスタルテはフォローユーザーのフォロー制限を確認する手段を提供しません。
そのためフォローAPIを叩くことで初めてそのアカウントをフォロー出来るのか、フォローリクエストになるのか知ることになります。
標準エラー型でフォローできたのかフォローリクエストになったのか結果が帰ってきます。
フォローリクエストは原則1回しか送る事は出来ません。
secret_wordは8文字までの文字列です。
messageは50文字までの文字列です。こちらは相手のユーザーにメッセージを送信することが出来ます。
メッセージは相手の設定によっては送信されません。
メッセージを相手が読める設定になっているかどうかをしる手段をネオアスタルテは提供しません。
投稿
エンドポイント
api/statuses/new_status
リクエストタイプ
POST
認証タイプ
Bearer
ヘッダー
Authorization: 必須
パラメータ
{
content: 必須 String型,
visibility: オプション String型 [現在はpublicのみ実装、そのほかは未実装],
reply_destination_id: オプション String型 [未実装],
sensitive: オプション String型 [未実装],
introduction_sentence: オプション String型 [未実装],
}
レスポンス
{
id: String型,
account: {account_data型},
content: String型,
visibility: String型,
reply_destination_id: <String型>,
reply: Boolean型,
sensitive: Boolean型,
introduction_sentence: String型,
client_data: {client_owner_data型},
create_at: Date型,
update_at: Date型
}
エラーレスポンス：標準エラー型
パブリックタイムラインの取得
エンドポイント
api/timelines/public
リクエストタイプ
GET
認証タイプ
Bearer
ヘッダー
Authorization: 必須
パラメータ
{
newest_id: オプション String型 [指定することでそれより後の投稿を返します],
oldest_id: オプション String型 [指定することでそれより前の投稿を返します]
}
レスポンス
{
newest_id: <String型>,
oldest_id: <String型>,
data: Array型[{}, {}, {}, {}, ・・・・, {}] [Max20件のデータが含まれます。中に含まれるデータは、投稿の項のレスポンスデータと同じものが配列型で含まれています。]
}
エラーレスポンス：標準エラー型
ガチャのバックログを取得する
エンドポイント
api/games/gacha_back_log
スコープ
games
リクエストタイプ
GET
認証タイプ
Bearer
ヘッダー
Authorization: 必須
レスポンス
{
backlog: Array型[{}, {}, {}, {}, ・・・・, {}] [10件のデータが含まれます。中に含まれるデータは、content, fake, rarity の3つです。基本はString型ですが、fakeはnullを含む場合があります。],
update_at: <String型>
}
エラーレスポンス：標準エラー型
～～～～～～～～～～～～～～～～～～～～～
クライアント製作者向け
～～～～～～～～～～～～～～～～～～～～～
クライアント登録
エンドポイント
api/apps/create_application
リクエストタイプ
POST
認証タイプ
Bearer
ヘッダー
Authorization: 必須
パラメータ
{
name: 必須 String型 [一部禁止されている文字列が存在します。],
website: 必須 String型 [自分のwebページを宣伝することができます],
scope_read: オプション Bool型 [未指定の場合でもtrueになります。意図的にfalseにすることも可能です],
scope_write: オプション Bool型 [未指定の場合falseになります。投稿、プロフィール等編集権限],
scope_follow: オプション Bool型 [未指定の場合falseになります。フォロー/フォロワー編集権限],
scope_push: オプション Bool型 [未指定の場合falseになります。通知の受け取り権限],
scope_games: オプション Bool型 [未指定の場合falseになります。ゲームコンテンツ権限, この権限は一部投稿を行う場合があります。],
}
レスポンス
{
client_name: String型,
client_id: String型,
client_secret: String型,
website: String型,
scopes: String型
}
エラーレスポンス：標準エラー型
現在UIでのクライアント製作が実装されていないため
クライアント開発者はcurlやREST APIクライアント等を使ってクライアント登録をする必要があります。
その際、トークンを用いてクライアント登録をしますが、トークンを発行にはクライアントが必要です。
この循環を回避するため開発者は以下のクライアントデータをパラメータとして利用することがで来ます。
なお、ここではclient_idとclient_secretを公開していますが、
実際のクライアント開発ではclient_secretはユーザーが容易に見ることができないように隠すことが推奨されます。
今後実装されるAPIで開発者はクライアントのデータを変更できるようになりますが、その時に
クライアント開発者のトークン、client_id、client_secretの3つが必要となります。
クライアント開発者のトークン、client_id、client_secret が何らかの手違いで流出してしまった場合、クライアントの情報をこのAPIを用いて書き換えられる可能性があります。
十分注意してください。
client_name: API client
client_id: 01FQPQ6FR6XMDJ161EBZPYE33Q
client_secret: eWLuPziC_htXZRT9AND5fvImj26Ox.YpSlU~aqMGk0-osg1QH8b+/4EFy7VKdBwJ
scope: read write