“图书红黑榜”开放API

jinxuliang2 发表于   2017/3/4 11:22:18,阅读次数: 1826

关于第三方应用调用本网站“图书红黑榜”开放API的文档

本网站向第三方开放REST API访问本站之图书资源,其方法如下:

获取指定Id值的图书详细信息

系统为每本图书提供一个唯一的标识,可以通过它提取指定图书的详细信息,其调用方法为:

发出HTTP GET请求,格式为:

http://jinxuliang.com/openservice/api/bookService/{bookId}

例如:

http://jinxuliang.com/openservice/api/bookservice/584fb689c89f0219f01ab7d6

将收到响应:

{

"bookId":"584fb689c89f0219f01ab7d6",

"name":"大数据时代:生活、工作与思维的大变革",

"publisherName":"湛庐文化",

"publisherId":"584fb689c89f0219f01ab7d5",

"publishDate":"2010-12-01T08:00:00+08:00",

"authorName":"维克托·迈尔-舍恩伯格",

"authorId":"584fb689c89f0219f01ab7d4",

"score":5,

"viewCount":0,

"description":"<span style=\"font-size:medium;\">《大数据时代》是国外大数据系统研究的先河之作,……大数据已经成为了新发明和新服务的源泉,而更多的改变正蓄势待发。书中展示了谷歌、微软、IBM、苹果、facebook、twitter、VISA等大数据先锋们具价值的应用案例。</span>",

"bookCoverId":"584fb8c6c89f0219f01ab7df",

"subjects":[

{"_id":"584be9edc89f020fa4ef1af3","name":"好书还是坏书?亮出你的观点!","description":"你为什么认为这本书好(或坏)?说出理由来。","category":"List"},

{"_id":"584bec0cc89f020fa4ef1af5","name":"网上书店本书详情页面链接及读者评论页链接","description":"京东、当当、亚马逊等网上书店中本书的详情页面的链接,以及豆瓣等网站上本书的页面链接","category":"HyperLink"},

{"_id":"584fb71ac89f0219f01ab7da","name":"阅读过程随手记(读书笔记)","description":"在阅读本书的过程中,随手记下的笔记","category":"List"}],

"categories":[

{"categoryTreeId":"584f958fc89f0219f01ab79a","categoryId":"584f9cc8c89f0219f01ab7c8","category":"大数据与人工智能"},

{"categoryTreeId":"584f958fc89f0219f01ab79a","categoryId":"584f95d5c89f0219f01ab79d","category":"科普类图书"}

]

}

图书的详细信息包容其主题集合和所属种类集合。

获取新的10本图书信息

HTTP GET请求,其URL为:

http://jinxuliang.com/openservice/api/bookService/newest

返回图书的简要信息,其数据格式为:

[

  {"bookId":"58a95fdba3c664106441f171",

    "bookName":"计算机类图书1",

    "authorName":"张三","authorId":"58a95fdaa3c664106441f170",

    "publisherName":"电子工业出版社",

    "publisherId":"585260fdc89f0215bc1e6d94",

    "publishDate":"2017-02-13T08:00:00+08:00",

     "score":4,

    "viewCount":12

},

{...},

...

]

提取图书分类树

方法:发出HTTP Get请求,其URL为:

http://jinxuliang.com/openservice/api/bookService/categoryTree

返回一个Json格式的嵌套对象,其结构与树结构一一对应,一个示例如下:

{"treeId":"584f958fc89f0219f01ab79a",

    "description":"图书分类树",

    "treeData":[

        {

            "nodeId":"584f958fc89f0219f01ab79b","name":"计算机类图书",

             "children":[

                  {"nodeId":"584f9627c89f0219f01ab79f","name":"Java","children":[],"selected":false,"disable":false,"expanded":false},

                  {...},

                   ...

              ]

        },

       {...},

       ....

     ]

}

最外层代表一棵树,它的具体内容放在treeData属性中,注意这个属性是一个数组,它里面的每个对象都代表一棵子树,每棵子树的根节点就是这棵树的顶层一级节点。

每个树节点都有几个重要的属性:

nodeId是其标识,name代表树节点名字,selected代表是否被选中(在网页上,被选中的节点是高高显示的,手机客户端App可忽略此属性),disable表示是否禁用(在网页上,禁用的节点是灰色的,不响应鼠标操作,手机客户端App可忽略此属性),expanded用于表示本节点是展开还是折叠状态。

每个节点都有一个children属性,里面可以再递归地嵌套相同的Node对象,从而构成一个多层的多叉树。

分类提取图书

此功能依据用户在分类树中选择的节点,以及希望查看的图书质量好坏(好书、烂书、一般书),筛选显示满足条件的图书

HTTP POST请求,URL为:

http://jinxuliang.com/openservice/api/bookservice/category

Post上来的Json数据格式为:

{
    categories: [{treeId:XXXX,nodeId:XXXX},{...},...],
    scoreLevel: 图书类别标识(可选值best,ordinary,worse之一),
    pageIndex: 页码,
    pageSize: 每页记录数(可选,默认值为5)
};

其中categories数组中可以包容多个分类对象,通常情况下,是用户当前所选中的节点及其它的所有下属子节点。如果不需要这个特性,可以只传当前选中的分类树中的节点值,而不理会它包容的下属子节点。

客户端得到的数据样式为:

[
{"score":评分值,
"bookId":"书标识值",
"bookName":"书名",
"authorName":"作者名",
"authorId":"作者标识",
"viewCount":访问次数},
{……}
]

另外,HTTP响应的首部中,有一个自定义的Header,其名字为total-items,它包容符合条件的图书总数值

示例:

POST数据:

{

   "categories":[
         {"treeId":"584f958fc89f0219f01ab79a","nodeId":"584f962cc89f0219f01ab7a0"}
       ],
   "scoreLevel":"best",
   "pageIndex":1

}

收到结果:

[
  {

     "score":5,
    "bookId":"58a9588fa3c664157c95afaa",
     "bookName":"C#1",
     "authorName":"Lawrence D.Spencer",
     "authorId":"57f207bdc89f020dd44c3c3c",
      "viewCount":2

   },
  {……},

   ...

]

按名字模糊查找图书

HTTP GET请求,格式为:

http://jinxuliang.com/openservice/api/bookservice/find/{name}

例如:

要查找书名中包容“大”的图书,发出以下请求:

http://jinxuliang.com/openservice/api/bookservice/find/%E5%A4%A7

上面的“%E5%A4%A7”是“大”这个汉字的编码,浏览器和许多框架会自动地完成这个工作。

收到响应:

[

{"bookId":"584fb689c89f0219f01ab7d6",

"bookName":"大数据时代:生活、工作与思维的大变革",

"authorName":"维克托·迈尔-舍恩伯格",

"authorId":"584fb689c89f0219f01ab7d4",

"publisherName":"湛庐文化",

"publisherId":"584fb689c89f0219f01ab7d5",

"publishDate":"2010-12-01T08:00:00+08:00",

"score":5,

"viewCount":0},

……

]

按照Id提取作者信息

每个作者有一个唯一的Id,使用以下方法提取作者的详细信息。

HTTP GET: 

http://jinxuliang.com/openservice/api/authorservice/detail/{authorId}

例如:

http://jinxuliang.com/openservice/api/authorservice/detail/584fb689c89f0219f01ab7d4

得到以下结果:

{"_id":"584fb689c89f0219f01ab7d4",

"authorName":"维克托·迈尔-舍恩伯格",

"books":[

{"name":"大数据时代:生活、工作与思维的大变革",

"authorName":"维克托·迈尔-舍恩伯格",

"authorId":"584fb689c89f0219f01ab7d4",

"publisherName":"湛庐文化",

"publisherId":"584fb689c89f0219f01ab7d5",

"publishDate":"2010-12-01T08:00:00+08:00",

"bookId":"584fb689c89f0219f01ab7d6"}

],

"extraInfos":null,

"aboutAuthor":null

}

作者的详细信息主要包容其所著的书,以及他的描述及附加信息等,如果某项属性没值,则返回null。

提取图书封面

每本书有一个封面。可以通过图书Id提取这个封面。

其方法如下:

发出HTTP请求:http://localhost:12108/api/bookservice/GetCoverByBookId/{bookId}

例如:

http://localhost:12108/api/bookservice/GetCoverByBookId/584fb689c89f0219f01ab7d6

将收到一个JPGE图片的响应。

在HTTP响应的首部:Content-Type: image/jpeg,指明图像编码类型

在响应的Body中,即为图片的二进制数据。

==============================================

获取指定出版社的详细信息

HTTP请求,其格式为:

http://jinxuliang.com/openservice/api/publisherservice/detail/{publisherId}

示例:

http://localhost:12108/api/publisherservice/detail/584fb689c89f0219f01ab7d5

返回结果:

{"_id":"584fb689c89f0219f01ab7d5","name":"湛庐文化","description":"湛庐文化是浙江人民出版社拥有的品牌"}

提取指定出版社的所有图书

HTTP GET请求,其格式为:

http://jinxuliang.com/openservice/api/publisherservice/books/{publisherId}

示例:

http://jinxuliang.com/openservice/api/publisherservice/books/584fb689c89f0219f01ab7d5

返回指定出版社的所有图书:

[

{

"name":"大数据时代:生活、工作与思维的大变革",

"authorName":"维克托·迈尔-舍恩伯格",

"authorId":"584fb689c89f0219f01ab7d4",

"publisherName":"湛庐文化",

"publisherId":"584fb689c89f0219f01ab7d5",

"publishDate":"2010-12-01T08:00:00+08:00",

"bookId":"584fb689c89f0219f01ab7d6"

},

...

]

=======================================================

提取本书特定专题下的所有书评

每本书可以有多个专题,其中有一种类型的专题,它只包容一个超链接,可用于链接到比较长的文章(通常是作为长篇书评,以博客文章的形式出现)

本API提取出它们。

HTTP Get请求:

http://jinxuliang.com/openserivce/api/bookservice/{bookId}/reviews/{subjectId}

示例:

http://jinxuliang.com/openserivce/api/bookservice/5856000ac89f0212d028a09d/reviews/58ba24b2a3c664162057bf6b

返回结果:

[{

"_id":"58ba2511a3c664162057bf70",

"bookId":"5856000ac89f0212d028a09d",

"bookSubjectId":"58ba24b2a3c664162057bf6b",

"reader":{"id":"04d80189-e09f-49b6-a247-33609d144d8f","name":"jinxuliang2"},

"linkText":"“图书红黑榜”开放API",

"url":"http://jinxuliang.com/blog/Article/Read/7a5330a8-fe82-4c1f-ad82-7f4efc86a3e8",

"postDate":"2017-03-04T10:23:13.607+08:00",

"helpful":0},

...

]

提取本书特定专题下的所有超链接

HTTP Get请求:

http://jinxuliang.com/openserivce/api/bookservice/{bookId}/links/{subjectId}

示例:

http://jinxuliang.com/openserivce/api/bookservice/5856000ac89f0212d028a09d/reviews/584bec0cc89f020fa4ef1af5

返回结果:

[{

"_id":"5856019cc89f0212d028a0a3",

"bookId":"5856000ac89f0212d028a09d",

"bookSubjectId":"584bec0cc89f020fa4ef1af5",

"reader":{"id":"04d80189-e09f-49b6-a247-33609d144d8f","name":"jinxuliang"},

"linkText":"京东链接",

"url":"https://item.jd.com/11056556.html",

"content":"无",

"postDate":"2016-12-18T11:25:17.349+08:00","helpful":0}

]

它与书评的最大区别在于它有一个content属性,可用于附加一些说明信息

提取本书特定专题下的所有读者评论(或目录等单项文本)

这主要是针对类型为List的专题的。

HTTP GET请求,其格式为:

http://jinxuliang.com/openserivce/api/bookservice/{bookId}/opinions/{subjectId}

http://jinxuliang.com/openserivce/api/bookservice/{bookId}/singleText/{subjectId}

示例:

http://jinxuliang.com/openservice/api/bookservice/5856000ac89f0212d028a09d/opinions/584be9edc89f020fa4ef1af3

返回:

[{

"_id":"5856018cc89f0212d028a0a2",

"bookId":"5856000ac89f0212d028a09d",

"bookSubjectId":"584be9edc89f020fa4ef1af3",

"reader":{"id":"04d80189-e09f-49b6-a247-33609d144d8f","name":"jinxuliang"},

"content":"<p>虽然原书是十多年以前写的,但写得极好,详尽地介绍了HTTP协议的相关内容。</p><p>强烈建议所有从事Web开发的人都认真地了解一下HTTP协议,而这本书会是一个好的起点。</p><p>可惜本书没有新版,一些新的进展没有在书中展现,比如HTTP 2。</p>",

"postDate":"2016-12-18T11:25:00.776+08:00",

"helpful":4},

...

]

访问单项文本类型(比如目录)的例子:

http://jinxuliang.com/openservice/api/bookservice/5856000ac89f0212d028a09d/singleText/58ba2fa6a3c66427e0a8e7d6

返回结果:

[{"_id":"58ba3003a3c66427e0a8e7db",
"bookId":"5856000ac89f0212d028a09d",
"bookSubjectId":"58ba2fa6a3c66427e0a8e7d6",
"reader":{"id":"04d80189-e09f-49b6-a247-33609d144d8f","name":"jinxuliang2"},
"content":"第一部分 HTTP:Web的基础<br />第1章 HTTP概述<br />……索引",
"postDate":"2017-03-04T11:09:55.263+08:00",
"helpful":0}]


附件清单



评论于: