rest api doc
v2021.2
Inspire هو مركز مجتمع موثوق به يساعد الباحثين على مشاركة وإيجاد معلومات علمية دقيقة في فيزياء الطاقة العالية. بالإضافة إلى واجهة ويب منتظمة للوصول التفاعلي إلى محتواه ، يتم توفير واجهة برمجة تطبيقات REST للوصول البرنامجي. يشرح الوثيقة الحالية كيفية استخدام API REST.
إذا كنت تستخدم واجهة برمجة التطبيقات في عمل علمي ، فيرجى الاستشهاد به باستخدام البيانات الوصفية التالية:
@article { Moskovic:2021zjs ,
author = " Moskovic, Micha " ,
title = " {The INSPIRE REST API} " ,
url = " https://github.com/inspirehep/rest-api-doc " ,
doi = " 10.5281/zenodo.5788550 " ,
month = " 12 " ,
year = " 2021 "
}إذا كانت لديك أي مشاكل تستخدم واجهة برمجة التطبيقات ، فأنت ترغب في بعض المساعدة ، أو لديك بعض الاقتراحات لتحسين واجهة برمجة التطبيقات أو وثائقها ، فيرجى فتح مشكلة أو الاتصال بنا.
يخضع استخدام واجهة برمجة التطبيقات لشروط استخدامنا. كما هو موضح هناك بمزيد من التفصيل ، فإن معظم البيانات الوصفية متوفرة بموجب ترخيص CC0 ، لكن القيود تنطبق على بعض الحقول ، ولا يُسمح بمجموعة كبيرة من عناوين البريد الإلكتروني.
واجهات برمجة التطبيقات (API) مريحة بشكل عام وتؤدي الإرجاع إلى JSON افتراضيًا. هذا يعني على سبيل المثال أنه سيُرجع رمز حالة HTTP 404 إذا لم يكن من الممكن العثور على سجل.
بشكل عام ، فإن معظم الصفحات التي تحصل عليها من خلال موقع الويب لديها تمثيل مماثل في API التي تم الحصول عليها عن طريق بادئة مكون المسار بعنوان URL باستخدام /api/ . على سبيل المثال ، البيانات المعروضة في
https://inspirehep.net/literature?sort=mostrecent&size=25&page=1&q=title api
متاح من خلال API في
https://inspirehep.net/api/literature?sort=mostrecent&size=25&page=1&q=title api
حاليًا فقط عمليات القراءة فقط على السجلات مسموح بها ، وتستخدم جميعها طريقة GET HTTP.
لاحظ أن جميع الأمثلة يتم عرضها بطريقة قابلة للقراءة البشرية ، ولكن غالبًا ما تحتاج معلمات الاستعلام إلى ترميز عناوين URL. على وجه الخصوص ، يجب استبدال المساحات بنسبة %20 .
من أجل تجنب الخادم الساحق ، نقوم بتطبيق حدود الأسعار لكل عنوان IP: يُسمح لكل عنوان IP 15 طلبًا في نافذة 5S. إذا تجاوزت هذه الحدود ، فستتلقى استجابة باستخدام رمز حالة HTTP 429 قبل المحاولة مرة أخرى.
للحصول على البيانات الوصفية في سجل واحد ، استخدم النوع التالي من عنوان URL:
https://inspirehep.net/api/{identifier-type}/{identifier-value}
يتم دعم فئتين رئيسيتين لمعرفات السجلات (أي أزواج من {identifier-type} و {identifier-value} ).
هذه هي نفس المعرفات كما تظهر في عناوين URL على موقع الويب ويمكن استخدامها أيضًا للبحث. يمكن أن يأخذ {identifier-type} القيم التالية:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdata و {identifier-value} هو رقم يحدد السجل المحدد في قاعدة بيانات Inspire (تسمى أيضًا معرف السجل أو recid ). على سبيل المثال،
https://inspirehep.net/api/literature/451647
هو سجل ورقة إعلانات/CFT الشهيرة في Maldacena ، في حين
https://inspirehep.net/api/conferences/1642486
هو سجل مؤتمر ICHEP 2018.
هذه معرفات مستمرة لم يتم تعيينها بواسطة Inspire ولكن مع ذلك تحدد السجل بشكل فريد (إذا كان هناك سجل للمعرف المقابل في النظام).
يمكن استخدام المعرفات الخارجية التالية:
{identifier-type} | {identifier-value} (أمثلة) | الاستخدام |
|---|---|---|
doi | 10.1103/PhysRevLett.19.1264 | للحصول على سجل أدبي مُعطى DOI |
arxiv | 1207.7214 ، hep-ph/0603175 | للحصول على سجل أدبي معرف Arxiv |
orcid | 0000-0003-3897-046X | للحصول على سجل مؤلف معرف orcid |
على سبيل المثال،
https://inspirehep.net/api/orcid/0000-0002-9079-593X
هل سجل مؤلف ستيفن هوكينجز.
بشكل افتراضي ، سيكون استجابة API عند استرداد سجل واحد بتنسيق JSON ويحتوي على المفاتيح التالية:
| مفتاح | وصف |
|---|---|
id | المعرف المستخدم لاسترداد السجل |
created | الطابع الزمني لإنشاء السجل في UTC |
updated | آخر تحديث طابع زمني للسجل في UTC |
links | روابط للموارد المتعلقة بالسجل |
metadata | بيانات تعريف السجل |
أيا كان المعرف الذي يتم استخدامه لاسترداد السجل ، فسيكون موجودًا أيضًا (وكذلك المعرفات الأخرى التي تنتمي إلى هذا السجل) داخل metadata .
يحتوي كائن links على روابط إلى البيانات الوصفية المتعلقة بهذا السجل ولكن لم يتم تضمينها مباشرة في السجل (على سبيل المثال معلومات الاقتباس) ، وتنسيقات التسلسل البديلة (مثل Bibtex).
يحتوي كائن metadata على بيانات تعريف السجل المناسبة. تحتوي جميع السجلات على مفتاح $schema ، والذي يربط بمخطط JSON (المسودة 4) التي يطيعها بيانات التعريف القياسية. يمكن العثور على وثائق مفصلة حول الحقول الممكنة لكل مخطط ويمكن العثور على معناها في وثائق المخطط.
على سبيل المثال ، تتوافق metadata لسجلات Literature مع مخطط hep ، الذي تم توثيق حقوله هنا.
من الممكن الحصول على تمثيل لسجل (أو عدة سجلات) بتنسيق مختلف من JSON الافتراضي. يمكن القيام بذلك بطريقتين بديلين:
format={format-name} سلسلة استعلام URL ، أوAccept HTTP إلى نوع محدد MIME. حاليًا ، يتم دعم التنسيقات التالية (فقط لسجلات Literature ):
{format-name} | نوع MIME | وصف |
|---|---|---|
| جيسون | التطبيق/JSON | تنسيق JSON الافتراضي |
| bibtex | التطبيق/x-bibtex | تنسيق اقتباس bibtex |
| اللاتكس-الاتحاد الأوروبي | Application/VND+Inspire.latex.eu+x-latex | تنسيق الاقتباس اللاتكس (الاتحاد الأوروبي) |
| اللاتكس-الولايات المتحدة | التطبيق/VND+Inspire.latex.us+x-latex | تنسيق الاقتباس اللاتكس (الولايات المتحدة) |
| السيرة الذاتية | النص/VND+Inspire.html+html | تنسيق CV HTML Citation |
يمكن أيضًا العثور على روابط للتنسيقات البديلة في كائن links داخل استجابة JSON.
على سبيل المثال ، للحصول على ورقة Glashow الشهيرة على التفاعلات الضعيفة في تنسيق bibtex ، استخدم إما معلمة تنسيق:
https://inspirehep.net/api/literature/4328?format=bibtex
أو ما يعادل التفاوض على المحتوى (يستخدم المثال أداة سطر أوامر curl لتعيين الرأس):
curl -H "Accept: application/x-bibtex" https://inspirehep.net/api/literature/4328
من أجل الحصول على نتائج للبحث بدلاً من الحصول على بيانات سجل واحد بواسطة معرفه ، استخدم عنوان URL الأساسي للنموذج التالي:
https://inspirehep.net/api/{record-type}?{query-string}
يجب أن يكون {record-type} واحد من:
literatureauthorsinstitutionsconferencesseminarsjournalsjobsexperimentsdataلاحظ أن هذه هي نفس أنواع المعرفات الداخلية.
قد يحتوي {query-string} على عدة {parameter}={value} مفصولة بواسطة & . يتم دعم المعلمات التالية دائمًا:
{parameter} | وصف {value} |
|---|---|
q | استعلام البحث |
sort | ترتيب الفرز |
size | عدد النتائج التي تم إرجاعها لكل صفحة |
page | رقم الصفحة |
fields | الحقول في البيانات الوصفية المراد إرجاعها |
بالإضافة إلى ذلك ، اعتمادًا على {record-type} ، تتوفر مرشحات Facet المختلفة لتقييد مجموعة النتائج. أنها تعمل بالضبط بنفس الطريقة كما في الموقع.
على سبيل المثال ، للحصول على المؤتمرات القادمة من 6 إلى 10 ، يمكن استخدام عنوان URL التالي:
https://inspirehep.net/api/seminars?size=5&page=2&start_date=upcoming
للحصول على أحدث 10 أوراق تم الاستشهاد بها 1000 مرة على الأقل ، استخدم:
https://inspirehep.net/literature?sort=mostrecent&size=10&q=topcite 1000+
تتيح وسيطة q Query String لتحديد استعلام بحث لا يطابق سوى مجموعة فرعية من السجلات.
بالنسبة لسجلات الأدب (التي تم الحصول عليها من خلال نقطة نهاية /api/literature ) ، يتم استخدام بناء جملة بحث مخصص للتوافق مع الأبراج والملهم القديم. تم شرحه هنا. بالإضافة إلى ذلك ، يمكن البحث في أي مجال من بيانات بيانات القياس السجل باستخدام مساره المقدم عن طريق تسلسل المفاتيح المتداخلة مع . ، تليها : والقيمة للبحث عن.
على سبيل المثال ، للعثور على جميع الأوراق التي تحتوي على ملخص من Springer ، يمكن استخدام البحث التالي:
https://inspirehep.net/api/literature?q=abstracts.source:Springer
للعثور على جميع أوراق المؤتمرات التي تشير إلى إدوارد ويتن ، يمكنك استخدام:
https://inspirehep.net/api/literature?q=tc conference paper and refersto a E.Witten.1
للتحقق مما إذا كان هناك حقل ، يمكنك استخدام * Wildcard. على سبيل المثال ، للعثور على جميع الأوراق التي تحتوي على DOI ، يمكنك استخدام:
https://inspirehep.net/api/literature?q=dois.value:*
بالنسبة لأنواع أخرى من السجلات ، يتم استخدام بناء جملة سلسلة الاستعلام Elasticsearch. هنا أيضًا ، يمكن البحث في أي مجال من بيانات بيانات القياس السجل باستخدام مساره المقدم عن طريق تسلسل المفاتيح المتداخلة مع . ، تليها : والقيمة للبحث عن.
على سبيل المثال ، للعثور على جميع التجارب باستخدام مسرع CERN Proton-Snchotron (PS) ، استخدم
https://inspirehep.net/api/experiments?q=accelerator.value:PS
وبالمثل ، للعثور على مؤلف مع معرف إلهام معين ، استخدم
https://inspirehep.net/api/authors?q=ids.value:INSPIRE-00140145
يعتمد الترتيب الذي يتم فيه إرجاع نتائج البحث على ما إذا كان يتم توفير استعلام بحث.
بشكل افتراضي ،
q ) ، يتم فرز النتائج مع أحدث السجلات أولاً ،q ) ، يتم فرز النتائج مع الأكثر صلة أولاً. يمكن تجاوز هذا السلوك مع معلمة الاستعلام sort={sort-order} . الخيارات التالية مدعومة:
{record-type} | {sort-order} | وصف |
|---|---|---|
literature | mostrecent | تظهر أحدث السجلات أولاً (استنادًا إلى موعد مبكر في البيانات الوصفية) |
literature | mostcited | تظهر السجلات مع معظم الاستشهادات أولاً |
jobs | mostrecent | تظهر الوظائف التي تم إنشاؤها مؤخرًا أولاً |
jobs | deadline | وظائف مع الموعد النهائي المبكر تظهر أولا |
conferences | dateasc | تظهر المؤتمرات مع أقرب تاريخ البدء أولاً |
conferences | datedesc | تظهر المؤتمرات مع آخر تاريخ البدء أولاً |
seminars | dateasc | تظهر الحلقات الدراسية مع أقدم وقت البدء أولاً |
seminars | datedesc | تظهر الحلقات الدراسية التي تحتوي على أحدث وقت لبدء أولاً |
على سبيل المثال ، سيعيد عنوان URL التالي أوراق Edward Witten العشرة الأكثر استشهادًا:
https://inspirehep.net/api/literature?sort=mostcited&size=10&q=a E.Witten.1
يتم إرجاع نتائج البحث في صفحات للحد من حجم الاستجابة. بشكل افتراضي ، يتم إرجاع 10 نتائج لكل صفحة ويتم إرجاع الصفحة الأولى من النتائج. للوصول إلى الصفحات التالية ، يمكنك تمرير رقم الصفحة إلى معلمة استعلام page .
على سبيل المثال ، استخدم عنوان URL التالي للحصول على أوراق إدوارد ويتن من 31 إلى 40 الأكثر استشهادًا.
https://inspirehep.net/api/literature?sort=mostcited&page=3&q=a E.Witten.1
للذهاب إلى الصفحة التالية ، يمكن اتباع عنوان URL next لكائن links في الاستجابة (عند استخدام تنسيق JSON الافتراضي).
يمكن تجاوز عدد النتائج لكل صفحة بمعلمة استعلام size . من أجل عدم زيادة تحميل الخادم ، تكون القيمة القصوى المسموح بها هي 1000 ، وستحصل على استجابة مع رمز حالة HTTP 400 إذا تجاوزته.
على سبيل المثال ، للحصول على أكثر من 50 ورقة استشهاد بها إدوارد ويتن في وقت واحد ، يمكن استخدام عنوان URL التالي:
https://inspirehep.net/api/literature?sort=mostcited&size=50&q=a E.Witten.1
لاحظ أنه ، بالإضافة إلى حد النتائج التي تم إرجاعها لكل صفحة ، يوجد حاليًا قيود تقنية يمنع استرجاع أكثر من 10000 نتيجة لاستعلام البحث المحدد. يتمثل الحل البديل في تقسيم البحث الفردي إلى العديد من عمليات البحث التي تحتوي على أقل من 10000 نتائج لكل منهما. انظر هذا التعليق لمزيد من المعلومات.
استجابة البحث هو كائن JSON مع المفاتيح التالية:
hits : يحتوي على العدد الإجمالي للنتائج في total والسجلات في hits (وهي صفيف لها عناصرها نفس الهيكل كما في استجابة السجل الواحد)links : روابط للموارد ذات الصلة ، مثل التسلسلات البديلة لنتائج البحث والصفحة التالية في next . لاحظ أن بيانات التعريف القياسية (في hits.hits.metadata ) تحتوي على حقول أكثر من استجابة السجل الفردي. معظمها للاستخدام الداخلي: لا ينبغي الاعتماد على أي مجال ليس جزءًا من المخطط ، وليس هناك ما يضمن أنه سيبقى حاضرًا أو أن محتوىه لن يتغير ، باستثناء:
/api/literature| مفتاح | القيمة (مثال) | وصف |
|---|---|---|
earliest_date | 2020-03-18 | أقرب موعد في السجل |
citation_count | 243 | إجمالي عدد الاستشهادات التي تلقاها هذا السجل |
citation_count_without_self_citations | 213 | عدد الاستشهادات التي يتلقاها هذا السجل ، باستثناء الذات |
في بعض الأحيان ، قد تكون مهتمًا فقط ببعض الحقول المحددة من بيانات تعريف السجل وليس في السجل بأكمله. لتجنب توليد وتنزيل الاستجابة الكاملة ، والتي يمكن أن تكون كبيرة جدًا ، يمكن استخدام معلمة استعلام fields . يجب ضبطها على قائمة مفصولة بالفاصلة من الحقول التي يجب أن تكون حاضرة في بيانات التعريف القياسية.
على سبيل المثال ، سيعيد عنوان URL التالي فقط العناوين وأسماء المؤلفين والروابط إلى سجلات الانتماء للأوراق بأكثر من 1000 اقتباس:
https://inspirehep.net/api/literature?fields=titles,authors.full_name,authors.affiliations.record&q=topcite 1000+
تصفية البيانات الوصفية متوفرة فقط في عمليات البحث ، وليس لاستجابة السجل الفردي. ومع ذلك ، إذا كنت تعرف معرفًا للسجل الذي تريد الحصول على بيانات تعريف جزئية ، فيمكنك إجراء البحث عن هذا المعرف ، والذي سيعود سجلًا واحدًا فقط.
على سبيل المثال ، سيعطيك عنوان URL التالي عدد الاقتباس من السجل على https://inspirehep.net/api/Literature/4328:
https://inspirehep.net/api/literature?fields=citation_count&q=recid:4328
لاحظ أنه لا يمكن وضع قيود على عدد عناصر الصفيف ، ولكن فقط حدد ما إذا كان ينبغي أن يظهر هذا الصفيف على الإطلاق. على سبيل المثال ، لا يمكن تحديد المؤلفين العشرة الأوائل فقط ، ولكن من الممكن تجنب عودة المؤلفين من خلال عدم وضع authors (أو أي من حقوله الفرعية) بين fields .
بالإضافة إلى قواعد بيانات الببليوغرافيا ، تقدم Inspire أداة لإنشاء مراجع من ملف Tex يحتوي على أوامر cite{...} (أو المتغيرات) مع مفاتيح تحترم اتفاقية محددة تتيح للنظام استنتاج السجل المذكور. تتوفر المزيد من التعليمات التفصيلية في الأداة التفاعلية.
للوصول إليها من خلال واجهة برمجة التطبيقات ، تحتاج إلى تقديم طلب نشر إلى نقطة النهاية على https://inspirehep.net/api/bibliography-generator ، مع البيانات التالية:
format التي تكون قيمتها إما bibtex أو latex_eu أو latex_us اعتمادًا على تنسيق الببليوغرافي المطلوبfile واحد يحتوي على ملف مشفر النموذج كوسيطة. ستكون الاستجابة كائن JSON مع مفتاح data واحد يكون قيمته كائنًا يحتوي على عنوان URL لملف المراجع الذي تم إنشاؤه ضمن download_url ومجموعة من الأخطاء التي تمت مواجهتها تحت errors (وهو فارغ إذا لم تكن هناك أخطاء في العملية).
على سبيل المثال مع curl :
curl -XPOST -F "file=@/path/to/my/texfile.tex" "https://inspirehep.net/api/bibliography-generator?format=bibtex"
عند استخدام حزمة requests Python الشائعة ، يمكن القيام بذلك كما هو موضح في وثائقها.
تستخدم عدة أدوات بلغات مختلفة API هذه. قد تكون رمزها بمثابة مصدر مفيد للأمثلة في العالم الحقيقي.
إذا كنت ترغب في إدراج مشروعك ، فلا تتردد في إخبارنا بذلك.
