REST API
مرجع API
endpointها، قالب درخواست و پاسخ، مدل داده و خطاهای REST API.
آدرس پایه: https://avatarak.ir/api/v1. هر درخواست به یک کلید API نیاز دارد. پاسخها JSON هستند.
گرفتن یک پروفایل
GET /api/v1/profiles/{hash}
{hash} همان هش SHA-256 ایمیل است (۶۴ نویسهی هگز).
curl -H "Authorization: Bearer avk_YOUR_API_KEY" \
https://avatarak.ir/api/v1/profiles/f7254a5b7d62b61c5353da4a235812f4b2171e8f16fd876a210d268da1793fd7
{
"data": {
"hash": "f7254a5b7d62b61c5353da4a235812f4b2171e8f16fd876a210d268da1793fd7",
"username": "javid",
"profile_url": "https://avatarak.ir/javid",
"name_fa": "جاوید میرزایی",
"name_en": "Javid Mirzaei",
"headline": "Founder at Example",
"location": "Tehran, Iran",
"bio": "Full-stack engineer and founder.",
"website": "https://javid.example.ir",
"socials": { "github": "javid", "telegram": "javid_t" },
"links": [{ "label": "Blog", "url": "https://javid.example.ir/blog" }],
"verified_accounts": [{ "network": "website", "identifier": "javid.example.ir", "url": "https://javid.example.ir" }],
"avatar_url": "https://avatarak.ir/avatar/f7254a5b7d62b61c5353da4a235812f4b2171e8f16fd876a210d268da1793fd7"
}
}
پاسخ هدر Cache-Control: private, max-age=60 دارد.
گرفتن چند پروفایل با هم
POST /api/v1/profiles/lookup
بین ۱ تا ۱۰۰ هش را در یک درخواست بفرستید (تکراریها ادغام میشوند و حروف بزرگ پذیرفته است). نتیجه یک شیء با کلید هش است؛ هشی که پروفایل عمومی ندارد null میشود.
curl -X POST -H "Authorization: Bearer avk_YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"hashes":["f7254a5b7d62b61c5353da4a235812f4b2171e8f16fd876a210d268da1793fd7","84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee"]}' \
https://avatarak.ir/api/v1/profiles/lookup
{
"data": {
"f7254a5b7d62b61c5353da4a235812f4b2171e8f16fd876a210d268da1793fd7": { "username": "javid", "...": "same fields as above" },
"84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee": null
}
}
برای نمایش فهرست نظرات یا اعضا با یک تماس بهجای چند تماس از همین استفاده کنید.
شیء پروفایل
| فیلد | نوع | توضیح |
|---|---|---|
hash |
string | شناسهای که خواستهاید (با حروف کوچک) |
username |
string | نام کاربری پروفایل |
profile_url |
string | صفحهی عمومی پروفایل |
name_fa |
string | null | نام نمایشی فارسی |
name_en |
string | null | نام نمایشی انگلیسی |
headline |
string | null | عنوان کوتاه، مثل شغل یا شعار |
location |
string | null | موقعیت (متن آزاد) |
bio |
string | null | بیوگرافی کوتاه |
website |
string | null | وبسایت شخصی |
socials |
object | شبکه ← نام کاربری، مثل {"github": "javid"}؛ اگر خالی باشد {} |
links |
array | [{label, url, description?, image?}]؛ در صورت نبود [] |
verified_accounts |
array | [{network, identifier, url}]، فقط حسابهایی که کاربر مالکیتشان را ثابت کرده؛ برای لینکدین url برابر null است؛ در صورت نبود [] |
avatar_url |
string | null | آدرس آواتار، یا null وقتی کاربر عکس را مخفی کرده |
در اینجا socials فقط شناسه (handle) است؛ خروجی JSON عمومی آدرس کامل برمیگرداند و display_name، verified، created_at و updated_at را هم دارد.
خطاها
| وضعیت | بدنه | چه وقت |
|---|---|---|
401 |
{"message": "Invalid or missing API key."} |
کلید نیست، اشتباه است، یا سایتش حذف شده. هدر WWW-Authenticate: Bearer میفرستد. |
404 |
{"message": "Profile not found."} |
پروفایل وجود ندارد یا عمومی نیست. پایینتر را ببینید. |
422 |
{"message": "...", "errors": {"hashes": ["..."]}} |
lookup با فهرست خالی، بیش از ۱۰۰ هش، یا مقداری که ۶۴ نویسهی هگز نیست |
429 |
{"message": "Rate limit exceeded."} |
درخواست زیاد. بهاندازهی Retry-After ثانیه صبر کنید. |
چرا برای همه چیز یک 404
ایمیل ناشناخته، ایمیل تأییدنشده، ایمیل خصوصی و پروفایل مخفی، همگی همان 404 را میگیرند (و lookup مقدار null برمیگرداند). این عمدی است: جلوی کسی را میگیرد که بخواهد با API بفهمد کدام آدرسهای ایمیل حساب دارند. تلاش نکنید این حالتها را از هم جدا کنید. حریم خصوصی و محدودیتها را ببینید.