الواجهة البرمجيّة للتطبيق (API)

الدوائر: مفاهيم أساسيّة

الدوائر في تينه وُجدت لتجمع فردين أو أكثر في نفس المكان، بحيث يُمكنهم إضافة مناسبات تربطهم، أو إرسال الرسائل فيما بينهم (المحادثة)، و غيرها من النشاطات. الدوائر يُمكن أن تكون دوائر صغيرة بحيث تضمّ أفراد الأسرة الواحدة الصغيرة مثل الأب و الأم و الأبناء، و يُمكن أن تكون دائرة كبيرة تضمّ أفراد العائلة الكبيرة.

عرض و جلب الدوائر

يُمكن للمستخدم الحاليّ أن يجلب الدوائر التي يُعتبر فرداً فيها، و ذلك من خلال إرسال طلب GET إلى الرابط التالي، علماً أن تينه سيحاول ضمّ الفرد الحالي إلى دائرة مناسبة إذا لم يكن ضمن أيّ دائرة مًسبقة:

الطلب
GET 
{{teenah_api_url}}/circles

و سيردّ الخادم بمصفوفة من الدوائر التي يُعتبر المستخدم الحاليّ فرداً فيها، و قد تكون المصفوفة فارغة من الدوائر:

الردّ
200 
[
    {
        "id": "1",
        "name": "I5rEvWwxL9RlXIbV8ZZ5",
        "members_count": "2",
        "active": "1",
        "created_by": "2",
        "created_at": "2014-02-08 10:20:13",
        "updated_at": "2014-02-08 10:20:13"
    }
]
  • {id} رقم أو معرّف الدائرة.
  • {name} اسم الدائرة (اسم عشوائي مبدئياً).
  • {members_count} عدد أفراد الدائرة.
  • {active} حالة الدائرة من حيث الفعاليّة، فعّالة 1 أو غير فعّالة 0.
  • {created_by} رقم أو معرّف الفرد الذي قام بإنشاء هذه الدائرة.
  • {created_at} تاريخ و وقت إنشاء هذه الدائرة.
  • {updated_at} تاريخ و وقت آخر تحديث لهذه الدائرة.

إضافة دائرة

يُمكن للمستخدم الحاليّ إضافة دائرة شريطةَ أن تضمّ فردين أو أكثر و ذلك من خلال إرسال طلب POST إلى الرابط التالي:

الطلب
POST 
{{teenah_api_url}}/circles
  • {name} (مطلوب) اسم الدائرة المُراد إنشاؤها.
  • {members} (مطلوب) أفراد الدائرة المُراد إضافتهم، يكونون على هيئة مصفوفة مثلاً: [1,4].

و ردّ الخادم سيكون أحد الردود التالية: إمّأ 201 أو 400:

الردود
201 
{
    "message": "The circle has been created successfully.",
    "id": 2,
    "name": "Hello World"
}
  • {message} رسالة الإتمام العائدة من الخادم.
  • {id} رقم أو معرّف الدائرة.
  • {name} اسم الدائرة المُدخل.
400 
{
    "message": "Bad request."
}
  • {message} رسالة الخطأ العائدة من الخادم.

عرض أفراد الدائرة

يُمكن للمستخدم عرض أفراد دائرةٍ ما يمكنه الوصول إليها من خلال إرسال طلب GET إلى الرابط التالي:

الطلب
GET 
{{teenah_api_url}}/circles/{id}/members
  • {id} (مطلوب) رقم أو معرّف الدائرة.

و ردّ الخادم سيكون أحد الردود التالية: مصفوفة من الأفراد 200 أو 403:

الردود
200 
[
    {
        "id": "2",
        "gender": "male",
        "name": "حسام",
        "fullname": null,
        "nickname": null,
        "dob": null,
        "pob": null,
        "dod": null,
        "pod": null,
        "age": "0",
        "is_alive": "1",
        "photo": "https://teenahapp.s3.amazonaws.com/hesH4Olco.png",
        "location": null,
        "mobile": "96655*******",
        "email": null,
        "home_phone": null,
        "work_phone": null,
        "marital_status": "",
        "blood_type": null,
        "is_root": "0",
        "tribe_id": null,
        "created_at": "2014-02-02 17:56:34",
        "updated_at": "2014-02-05 12:07:30"
    },
    {
        "id": "3",
        "gender": "male",
        "name": "علي",
        "fullname": null,
        "nickname": null,
        "dob": null,
        "pob": null,
        "dod": null,
        "pod": null,
        "age": "0",
        "is_alive": "1",
        "photo": null,
        "location": null,
        "mobile": "96654*******",
        "email": null,
        "home_phone": null,
        "work_phone": null,
        "marital_status": "single",
        "blood_type": null,
        "is_root": "0",
        "tribe_id": null,
        "created_at": "2014-02-05 13:13:17",
        "updated_at": "2014-02-05 13:13:17"
    }
]
  • {id} رقم أو معرّف المستخدم الحاليّ.
  • {gender} جنس الفرد سواءً ذكراً أو أنثى: male أوَ female.
  • {name} اسم الفرد المرتبط بالمستخدم.
  • {fullname} الاسم الكامل للفرد المرتبط بالمستخدم.
  • {nickname} رسالة الخطأ التي يتم استقبالها من الخادم.
  • {dob} تاريخ ميلاد الفرد بالصياغة YYYYY-mm-dd.
  • {pob} مكان الميلاد للفرد المرتبط بالمستخدم.
  • {dod} تاريخ وفاة (لا سمح الله) الفرد بالصياغة YYYYY-mm-dd.
  • {pod} مكان الوفاة (لا سمح الله) للفرد المرتبط بالمستخدم.
  • {age} عمر الفرد بدءً من الصفر.
  • {is_alive} حالة نبض الفرد، حيّ يرزق أو أنّه متوفّى، 1 أو 0.
  • {photo} رابط الصورة الشخصيّة للفرد (إن وُجدت).
  • {location} مكان تواجد الفرد إن أحبب مشاركته.
  • {mobile} رقم جوّال الفرد المرتبط بالمستخدم.
  • {email} بريد الفرد الإلكترونيّ.
  • {home_phone} رقم هاتف المنزل للفرد (إن وُجد و إن أحبب مشاركته).
  • {work_phone} رقم هاتف العمل للفرد (إن وُجد و إن أحبب مشاركته).
  • {marital_status} الحالة الاجتماعيّة للفرد، أعزب (single)، متزوّج (married)، أرملة (widow) للأنثى أو طليقة (divorced).
  • {blood_type} فصيلة الدم بشكل إختياري و بالرمز الإنجليزي.
  • {is_root} هل هذا الفرد هو جدّ العائلة، 1: نعم، 0: لا.
  • {tribe_id} رقم الفرد الذي يمثّل جدّ العائلة (إن وُجد).
  • {created_at} تاريخ و وقت إنشاء المستخدم.
  • {updated_at} تاريخ و وقت آخر تحديث لهذا السجل.
403 
{
    "message": "Not authorized to use this resource."
}
  • {message} رسالة الخطأ العائدة من الخادم.

إضافة فرد (أفراد) إلى الدائرة

يُمكن للمستخدم الحاليّ إضافة أفراد إلى دائرةٍ من الدوائر التي يُعتبر ضمن أفرادها، و ذلك من خلال إرسال طلب POST إلى الرابط التالي مضمّناً مصفوفة تحوي الأفراد أو الفرد المُراد إضافته:

الطلب
POST 
{{teenah_api_url}}/circles/{id}/members
  • {id} (مطلوب) (في الرابط) رقم أو معرّف الدائرة.
  • {members} (مطلوب) (في الرؤوس) أفراد الدائرة المُراد إضافتهم، يكونون على هيئة مصفوفة مثلاً: [1,4].

و ردّ الخادم سيكون أحد الردود التالية: إمّا 201 أو 400 أو 403:

الردود
201 
{
    "message": "Members have been added to the circle successfully."
}
  • {message} رسالة الإتمام العائدة من الخادم.
400 
{
    "message": "Bad request."
}
  • {message} رسالة الخطأ العائدة من الخادم.
403 
{
    "message": "Not authorized to use this resource."
}
  • {message} رسالة الخطأ العائدة من الخادم.

ترك (الخروج من) دائرة

يُمكن للمستخدم الحاليّ أن يترك (أو يخرج) من دائرة حسب رغبته من خلال إرسال طلب GET إلى الرابط التالي:

الطلب
GET 
{{teenah_api_url}}/circles/{id}/leave
  • {id} (مطلوب) رقم أو معرّف الدائرة.

و ردّ الخادم سيكون أحد الردود التالية: إمّا 204 أو 403:

الردود
204
403 
{
    "message": "Not authorized to use this resource."
}
  • {message} رسالة الخطأ العائدة من الخادم.

عرض مناسبات الدائرة

يُمكن للمستخدم الحاليّ أن يعرض المناسبات الخاصّة بدائرةٍ من الدوائر التي يُعتبر فرداً فيها و ذلك من خلال إرسال طلب GET إلى الرابط التالي:

الطلب
GET 
{{teenah_api_url}}/circles/{id}/events
  • {id} (مطلوب) رقم أو معرّف الدائرة.

و ردّ الخادم سيكون أحد الردود التالية: مصفوفة من المناسبات التابعة للدائرة 200 أو 403:

الردود
200 
{{teenah_api_url}}/circles/{id}/leave
  • {id} (مطلوب) رقم أو معرّف الدائرة.
403 
{
    "message": "Not authorized to use this resource."
}
  • {message} رسالة الخطأ العائدة من الخادم.

عرض إحصائيات الدائرة

الإحصائيات تُعتبر من المميّزات الأساسيّة لتطبيق تينه، هذه الإحصائيات تخصّ كل دائرةٍ من الدوائر، فتُظهر الكثير من المعلومات للمستخدم الذي يطلبها ولكن لابدّ من أن يتواجد في الدائرة المطلوبة، و يقوم بذلك من خلال إرسال طلب GET إلى الرابط التالي:

الطلب
GET 
{{teenah_api_url}}/circles/{id}/stats
  • {id} (مطلوب) رقم أو معرّف الدائرة.

و ردّ الخادم سيكون أحد الردود التالية: إمّا 200 أو 403:

الردود
200 
{
    "members_count": "2",
    "males_count": "2",
    "females_count": "0",
    "alive_members_count": "2",
    "alive_males_count": "2",
    "alive_females_count": "0",
    "ages": [
        {
            "counts": "2",
            "ranges": "0-5",
            "social_medias": [],
            "updates_count": "0"
        }
    ],
    "educations": [],
    "education_majors": [],
    "companies": [
        {
            "members_count": "1",
            "company": null
        }
    ],
    "jobs": [
        {
            "title": "Software Developer",
            "members_count": "1"
        }
    ],
    "event_count": "2",
    "messages_count": "0",
    "medias_count": 0,
    "male_names": [
        {
            "name": "حسام",
            "members_count": "1",
            "social_medias": [],
            "updates_count": "0"
        },
        {
            "name": "علي",
            "members_count": "1",
            "social_medias": [],
            "updates_count": "0"
        }
    ],
    "female_names": [],
    "locations": [
        {
            "location": null,
            "members_count": "2",
            "social_medias": [],
            "updates_count": "0"
        }
    ]
}
  • {members_count} عدد أفراد الدائرة.
  • {males_count} عدد الذكور في الدائرة.
  • {females_count} عدد الإناث في الدائرة.
  • {alive_members_count} عدد الأفراد الأحياء في الدائرة.
  • {alive_males_count} عدد الذكور الأحياء في الدائرة.
  • {alive_females_count} عدد الإناث الأحياء في الدائرة.
  • {ages} مصفوفة تحوي الفئات العمرية في الدائرة و عدد المُنتسبين إليها.
  • {educations} مصفوفة بالمستويات التعليميةّة في الدائرة.
  • {education_majors} مصفوفة بالتخصّثات التعليميّة لأفراد الدائرة.
  • {companies} مصفوفة بالشركات و عدد العاملين فيها في الدائرة.
  • {jobs} مصفوفة من الوظائف التي يعمل بها أفراد الدائرة.
  • {event_count} عدد المناسبات للدائرة.
  • {messages_count} عدد الرسائل و المحادثات الخاصّة بالدائرة.
  • {medias_count} عدد الوسائط المتعدّدة للدائرة.
  • {male_names} مصفوفة تحوي أسماء الذكور المتداولة في الدائرة و عدد حامليها.
  • {female_names} مصفوفة تحوي أسماء الإناث المتداولة في الدائرة و عدد حامليها.
  • {locations} مصفوفة تحوي أماكن تواجد أفراد الدائرى.
403 
{
    "message": "Not authorized to use this resource."
}
  • {message} رسالة الخطأ العائدة من الخادم.

جلب رسائل الدائرة الغير مقروءة

يُمكن للمستخدم الحاليّ جلب آخر الرسائل (أو المحادثات) الغير مقروءة لدائرةٍ ما من خلال إرسال طلب GET إلى الرابط التالي، مع ملاحة أنّ الرسائل الغير مقروءة ستُعتبر مقروءة بمجرّد استدعاء هذا الرابط:

الطلب
GET 
{{teenah_api_url}}/circles/{id}/messages
  • {id} (مطلوب) رقم أو معرّف الدائرة.

و سيكون ردّ الخادم أحد الردود التالية: إمّا مصفوفة من الرسائل الغير مقروءة (قد تكون مصفوفة فارغة) 200 أو 403:

الردود
200 
[
    {
        "id": "1",
        "circle_id": "1",
        "message_id": "1",
        "member_id": "2",
        "status": "sent",
        "created_at": "0000-00-00 00:00:00",
        "updated_at": "0000-00-00 00:00:00",
        "message": {
            "id": "1",
            "category": "text",
            "content": "Hello World.",
            "created_by": "2",
            "created_at": "0000-00-00 00:00:00",
            "updated_at": "0000-00-00 00:00:00",
            "medias": [
                {
                    "id": "2",
                    "message_id": "1",
                    "media_id": "1",
                    "created_at": "0000-00-00 00:00:00",
                    "updated_at": "0000-00-00 00:00:00",
                    "media": {
                        "id": "1",
                        "category": "image",
                        "taste": null,
                        "url": "https://teenahapp.s3.amazonaws.com/uAPorkExVOS.png",
                        "created_by": "1",
                        "created_at": "2014-01-25 07:50:21",
                        "updated_at": "2014-01-25 07:50:21"
                    }
                }
            ]
        }
    }
]
  • {id} رقم أو معرّف السجل.
  • {circle_id} رقم أو معرّف الادائرة المُرسل إليها.
  • {message_id} رقم أو معرّف الرسالة بمحتواها.
  • {member_id} رقم أو معرّف الفرد المُرسل إليه.
  • {status} حالة الرسالة بالنسبة للمستقبل أو المُرسل، إمّا أن تكون معلّقة pending أو مُرسلة sent أو مقروءة read.
  • {created_at} وقت و تاريخ إنشاء السجل.
  • {updated_at} وقت و تاريخ آخر تحديث للسجل.
  • {message} مصفوفة فرعية تضمّ تفاصيل الرسالة.
  • {message.id} رقم أو معرّف الرسالة.
  • {message.category} تصنيف الرسالة، إمّا يكون نص text أو يكون تحديث update يأتي من تطبيق تينه.
  • {message.created_by} الفرد الذي أنشأ هذه الرسالة.
  • {message.medias} مصفوفة تضمّ الوسائط المرتبطة بالرسالة.
  • {message.medias.media} مصفوفة فرعيّة تضمّ تفاصيل الوسائط المتعدّدة.
  • {message.medias.category} تصنيف الوسائط المتعدّدة، إمّا صورة image أو فيديو video أو صوت sound.
  • {message.medias.taste} مذاق عن الوسائط المتعدّدة، مثل الصورة المصغّرة للصورة، أو مقطع بسيط من الفيديو، و هكذا.
  • {message.medias.url} رابط الوسائط المتعدّدة.
  • {message.medias.created_by} الفرد الذي قام بإنشاء الوسائط المتعدّدة.
403 
{
    "message": "Not authorized to use this resource."
}
  • {message} رسالة الخطأ العائدة من الخادم.
الشروع في الاستخدام المستخدمون الأفراد الدوائر المناسبات الوسائط المتعدّدة الرسائل الشبكات الاجتماعيّة الوكلاء الإكمال التلقائي