rest api doc下载 - rest api doc源代码下载

rest api doc

其他源码

v2021.2

下载

激发REST API

Inspire是一个值得信赖的社区枢纽，可帮助研究人员在高能量物理学中共享并找到准确的学术信息。除了用于交互式访问其内容的常规Web界面外，还为程序化访问提供了REST API。本文档说明了如何使用此REST API。

如果您在学术工作中使用API，请使用以下元数据引用它：

 @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 "
}

激发REST API
- 问题和评论
- 使用条款
- API概述
- 费率限制
- 获取记录
  - 内部标识符
  - 外部标识符
- 单记录响应
  - 链接
  - 元数据
- 更改格式
- 搜索
  - 搜索查询
  - 排序订单
  - 分页
  - 搜索响应
  - 元数据过滤
- 参考书目发生器
- API在野外使用

问题和评论

如果您使用API有任何问题，需要一些帮助，或者有一些建议改善API或其文档，请打开问题或与我们联系。

使用条款

API的使用受我们的使用条款的约束。如此处所述，大多数元数据都在CC0许可证下可用，但是限制适用于某些字段，并且不允许大量的电子邮件地址收集。

API概述

API通常是恢复的，默认情况下将返回JSON。例如，这意味着如果找不到记录，它将返回404 HTTP状态代码。

通常，您通过网站获得的大多数页面在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地址强制执行速率限制：在5S窗口中允许每个IP地址15个请求。如果您超出了这些限制，您将收到具有HTTP状态代码429的响应。请注意，由于超过速率限制对配额的速率限制而被阻止的请求，因此在收到429响应时，您需要至少等待5s在重试之前。

获取记录

要在单个记录中获取元数据，请使用以下类型的URL：

 https://inspirehep.net/api/{identifier-type}/{identifier-value}

支持记录标识符的两个主要类别（即{identifier-type}和{identifier-value} ）的两个主要类别。

内部标识符

这些是与网站上URL中显示的标识符相同的标识符，也可以用于搜索。 {identifier-type}可以采用以下值：

literature
authors
institutions
conferences
seminars
journals
jobs
experiments
data

{identifier-value}是一个数字，在Inspire数据库中识别给定记录（也称为记录ID或recid ）。例如，

 https://inspirehep.net/api/literature/451647

是Maldacena著名的广告/CFT纸的记录，而

 https://inspirehep.net/api/conferences/1642486

是ICHEP 2018会议的记录。

外部标识符

这些是持续的标识符，不是由Inspire分配的，但仍然唯一地标识了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 ID的作者记录

例如，

 https://inspirehep.net/api/orcid/0000-0002-9079-593X

是斯蒂芬·霍金斯（Stephen Hawkings）的作者记录。

单记录响应

默认情况下，检索单个记录时的API响应将处于JSON格式，并包含以下键：

钥匙	描述
`id`	标识符用于检索记录
`created`	UTC中记录的创建时间戳
`updated`	UTC中记录的最后更新时间戳
`links`	链接与记录相关的资源
`metadata`	记录的元数据

无论使用什么标识符来检索记录，它也将存在metadata内部（以及属于此记录的其他标识符）。

链接

links对象包含与此记录相关的元数据的链接，但未直接包含在记录中（例如引用信息）和替代序列化格式（例如Bibtex）。

元数据

metadata对象包含正确的记录的元数据。所有记录都有一个$schema密钥，该密钥链接到记录元数据的JSON模式（草案4）。有关每个模式的可能字段及其含义的详细文档可以在模式文档中找到。

例如， Literature的metadata记录符合hep模式，HEP模式在这里记录了其字段。

更改格式

可以获得与默认JSON不同格式的记录（或多个记录）的表示形式。这可以通过两种替代方式完成：

使用format={format-name} url查询字符串，或
通过内容协商，将Accept HTTP标头设置为特定的MIME类型。

当前，支持以下格式（仅用于Literature记录）：

`{format-name}`	哑剧类型	描述
JSON	应用程序/JSON	默认的JSON格式
Bibtex	应用程序/X-Bibtex	Bibtex引文格式
乳胶 - 欧盟	应用程序/vnd+inspire.latex.eu+x-latex	乳胶（EU）引文格式
乳胶 - US	应用程序/vnd+inspire.latex.us+x-latex	乳胶（美国）引文格式
简历	text/vnd+inspire.html+html	CV HTML引文格式

在JSON响应中的links对象中也可以找到指向替代格式的链接。

例如，要获取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}必须是：

literature
authors
institutions
conferences
seminars
journals
jobs
experiments
data

请注意，这些与内部标识符类型相同。

{query-string}可能包含几个{parameter}={value}对由&分开的。始终支持以下参数：

`{parameter}`	`{value}`的描述
`q`	搜索查询
`sort`	排序顺序
`size`	每个页面返回的结果数
`page`	页码
`fields`	元数据中的田地

此外，根据{record-type}不同，可以使用不同的方面过滤器来限制结果集。它们的工作方式与网站上的方式完全相同。

例如，要获得第六至第10个即将举行的会议，可以使用以下URL：

 https://inspirehep.net/api/seminars?size=5&page=2&start_date=upcoming

要获得至少1000次引用的10篇最新论文，请使用：

 https://inspirehep.net/literature?sort=mostrecent&size=10&q=topcite 1000+

搜索查询

q查询字符串参数允许指定仅与记录子集匹配的搜索查询。

对于文献记录（通过/api/literature端点获得），自定义搜索语法用于与Spiers和旧Inspire的向后兼容。这里解释了。此外，可以使用将嵌套键与与嵌套密钥相连给定的路径来搜索记录元数据的任何字段. ，然后是:以及搜索的价值。
例如，要查找来自Springer摘要的所有论文，可以使用以下搜索：

 https://inspirehep.net/api/literature?q=abstracts.source:Springer

要查找以爱德华·维滕（Edward Witten）为由的所有会议论文，您可以使用：

 https://inspirehep.net/api/literature?q=tc conference paper and refersto a E.Witten.1

要检查是否存在字段，您可以使用*通配符。例如，要查找所有具有DOI的论文，您可以使用：

 https://inspirehep.net/api/literature?q=dois.value:*

对于其他类型的记录，使用Elasticsearch查询字符串语法。在这里，也可以使用将嵌套键与与之相连的路径来搜索记录元数据的任何字段. ，然后是:以及搜索的价值。
例如，要使用CERN质子合成器（PS）加速器找到所有实验，请使用

 https://inspirehep.net/api/experiments?q=accelerator.value:PS

同样，要找到具有给定Inspire ID的作者，请使用

 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）的10篇论文：

 https://inspirehep.net/api/literature?sort=mostcited&size=10&q=a E.Witten.1

分页

搜索结果以页面返回以限制响应的大小。默认情况下，每个页面返回10个结果，并返回结果的第一页。要进入下一个页面，您可以将页码传递到page查询参数。

例如，使用以下URL获取爱德华·维滕（Edward Witten）的第31至40个最多引用的论文。

 https://inspirehep.net/api/literature?sort=mostcited&page=3&q=a E.Witten.1

要进行下一页，可以遵循响应中links对象的next URL（使用默认JSON格式时）。

每个页面的结果数可以用size查询参数覆盖。为了不超载服务器，最大允许的值为1000 ，如果超过该服务器，则使用HTTP状态代码400获得响应。

例如，要立即获得爱德华·维滕（Edward Witten）的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为单位）包含的字段多于单记录响应。其中大多数是用于内部用途的：不应依靠架构的任何一部分的任何字段，也不能保证它会保留或它的内容不会改变，但除了：

for /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

请注意，不可能对数组的元素数量限制，但只能选择该数组是否应该出现。例如，不可能仅选择前10位作者，但是可以通过不将authors （或其任何子场）在fields中避免回归作者。

参考书目发生器

除书目数据库外，Inspire还提供了一种工具，可以从包含cite{...}命令（或变体）的Tex文件中生成参考书目，其键尊重特定的惯例，该键允许系统推断引用的记录。交互式工具中提供了更详细的说明。

要通过API访问它，您需要在https://inspirehep.net/api/bibliography-generator上向端点提出发布请求，并提供以下数据：

一个format请求参数，其值为bibtex ， latex_eu或latex_us具体取决于所需的书目格式
一个形式编码的主体，其中包含单个file键，其中包含形式编码的文件作为参数。

响应将是一个带有单个data密钥的JSON对象，其值是在download_url下包含生成的书目文件的对象，并且在errors下遇到错误的错误（如果该过程中没有错误，则为空）。

例如用curl ：

 curl -XPOST -F "file=@/path/to/my/texfile.tex" "https://inspirehep.net/api/bibliography-generator?format=bibtex"

当使用流行的Python requests包时，可以按照其文档中的解释来完成此操作。

API在野外使用

几种不同语言的工具正在使用此API。他们的代码可能是实际示例的有用来源。

PHP：
- Inspirejson
Python：
- 引用
- ADS2INSPIRE
- 合着者
- track_inspire-hep_citations
- 启发
- InspireHepcitationStracker
佩尔：
- Inspirejson
Objective-C：
- sprees.app/inspire.app
- Bibdesk
JavaScript：
- Zotero Inspire Metadata Updater
打字稿：
- Raycast Inspire Hep搜索扩展
emacs lisp：
- Inspirehep.el