接口说明

开放API接口统一采用HTTP/REST风格。如无特殊说明,所有接口均采用HTTP协议方式。只有当涉及隐私等信息时会采用HTTPS协议方式。

术语定义

名称 描述
开放平台 由天翼阅读对外提供的服务平台
APP 合作伙伴的第三方应用
App ID 开放平台为特定版本的App分配的唯一标识序列号
App Secret 开放平台为特定版本的App分配的共享密钥,用于认证其身份
OAuth v2.0 开放用户授权协议v2.0,用于使获取过用户授权的应用可以在无需用户名和用户密码的条件下访问用户相关的私有资源
用户授权 用户对于合作应用能否通过开放能力接口调用、使用其私有在线信息或资源的许可
AccessToken

Access Token,简称令牌,合作应用可对开放能力接口进行合法调用的凭据;合作伙伴应用在调用开放能力接口之前须出示令牌并通过鉴权。访问令牌由开放平台集中颁发、统一管理。

Oauth2.0

天翼阅读平台采用OAuth2.0标准协议,作为用户身份验证与授权协议,OAuth2.0的技术说明文档可参考官方网站(http://oauth.net/2/)

本平台支持以下4种获取AccessToken的方式:

Authorization Code

简介

采用Authorization Code获取Access Token的授权验证流程又被称为Web Server Flow,适用于所有有Server端的应用,如Web/Wap站点、有Server端的手机/桌面应用等。

流程示意

对于应用而言,其流程由获取Authorization Code和通过Authorization Code获取Access Token这2步组成

获取Authorization Code

http://openapi.tyread.com /oauth/authorize

请求数据包格式
参数名 必选 说明 默认值
client_id True 申请组件时获得的API Key  
response_type True 此值固定为“code”  
redirect_uri True

授权后要回调的URI,即接收Authorization Code的URI。对于无Web Server的应用,其值可以是“oob”,此时用户同意授权后,授权服务会将Authorization Code直接显示在响应页面的页面中及页面

title中。

 
scope False 以空格分隔的权限列表,若不传递此参数,代表请求默认的basic权限。如需调用扩展权限,必需传递此参数,详细请参考权限列表  
state False 用于保持请求和回调的状态,防止第三方应用受到CSRF攻击。授权服务器在回调时(重定向用户浏览器到“redirect_uri”时),会原样回传该参数(如果state是0或false,接口会认为没有传递state参数)  
display False    
oauth_client False 是否为手机访问。手机访问:oauth_client=1;不是手机,无需此参数  
响应数据包格式

此 时授权服务会根据应用传递参数的不同,为用户展现不同的授权页面。如果用户在此页面同意授权,授权服务则将重定向用户浏览器到应用所指定的 “redirect_uri”,并附带上表示授权服务所分配的Authorization Code的code参数,以及state参数(如果请求 authorization code时带了这个参数)。

通过Authorization Code获取Access Token

http://openapi.tyread.com/oauth/token

通过上面第一步获得Authorization Code后,便可以用其换取一个Access Token。获取方式是,应用在其服务端程序中发送请求(推荐使用POST)到天翼阅读开放平台OAuth2.0授权服务的地址上,并带上以下5个必须参数:

client_id和client_secret需要通过http basic认证,即在http hreader中传入参数

Authorization:Basic base64(client_id:client_secret)

请求数据包格式
参数名 必选 说明 默认值
grant_type True 此值固定为“authorization_code”  
code True 通过上面第一步所获得的Authorization Code  
client_id True 应用的API Key  
client_secret True 应用的Secret Key  
redirect_uri True 该值必须与获取Authorization Code时传递的“redirect_uri”保持一致  
响应数据包格式

若参数无误,服务器将返回一段JSON文本,包含以下参数:

参数名 说明
access_token 要获取的Access Token
expires_in Access Token的有效期,以秒为单位
refresh_token 用于刷新Access Token 的 Refresh Token
scope Access Token最终的访问范围,即用户实际授予的权限列表(用户在授权页面时,有可能会取消掉某些请求的权限)
user_id 用户ID

若请求错误,服务器将返回一段JSON文本,包含以下参数:

参数名 说明
error_code 错误码
error 错误说明
request \/oauth2\/access_token

Implicit Grant

简介

采 用Implicit Grant方式获取Access Token的授权验证流程又被称为User-Agent Flow,适用于所有无Server端配 合的应用(由于应用往往位于一个User Agent里,如浏览器里面,因此这类应用在某些平台下又被称为Client- Side Application),如手机/桌面程序、浏览器插件等,以及基于JavaScript等脚本脚本语言实现的应用,他们的一个共同特点是, 应用无法妥善保管其应用密钥(App Secret Key),如果采取Authorization Code模式,则会存在泄漏其应用密钥的可能性。

流程示意

 

获取Access Token

http://openapi.tyread.com/oauth/ authorizetoken

请求数据包格式

为了获取Access Token,应用需要将用户浏览器(或手机/桌面应用中的浏览器组件)到开放平台OAuth2.0授权服务的地址上

参数名

必选

说明

client_id

True

申请组件时获得的API Key

response_type

True

此值固定为“token”

redirect_uri

True

授权后要回调的URI,即接受code的URI。对于无Web Server的应用,其值可以是“oob”。

scope

False

以空格分隔的权限列表,若不传递此参数,代表请求默认的basic权限。如需调用扩展权限,必需传递此参数,详细请参考权限列表

state

False

用于保持请求和回调的状态,授权服务器在回调时(重定向用户浏览器到“redirect_uri”时)原样回传该参数

display

False

登录和授权页面的展现样式,默认为“page”。手机访问时,此参数无效

client

False

是否为手机访问。手机访问:client=1;不是手机,无需次参数

 

响应数据包格式

若用户登录并接受授权,授权服务将重定向用户浏览器到“redirect_uri”,并追加以下参数

参数名

说明

access_token

要获取的Access Token

expires_in

Access Token的有效期,以秒为单位

refresh_token

用于刷新Access Token 的 Refresh Token

scope

Access Token最终的访问范围,即用户实际授予的权限列表(用户在授权页面时,有可能会取消掉某些请求的权限),关于权限的具体信息参考“权限列表”一节

state

如果请求获取Access Token时带有state参数,则将该参数原样返回

user_id

用户ID

 

Client Credentials

简介

此方式可以用于第三方获取公共资源

流程示意

获取Access Token

http://openapi.tyread.com/oauth/token

client_id和client_secret需要通过http basic认证,即在http hreader中传入参数

Authorization:Basic base64(client_id:client_secret)

 

请求数据包格式

参数名

必选

说明

grant_type

True

固定为“client_credentials”

client_id

True

应用的API Key

client_secret

True

应用的Secret Key

响应数据包格式

若参数无误,服务器将返回一段JSON文本,包含以下参数:

 

参数名

说明

access_token

要获取新的Access Token

expires_in

Access Token的有效期,以秒为单位

scope

Access Token最终的访问范围,即用户实际授予的权限列表

 

若请求错误,服务器将返回一段JSON文本,包含以下参数:

 

参数名

说明

error_code

错误码

error

错误说明

request

\/oauth2\/access_token

Refresh Token

简介

开 放平台的应用,无论通过OAuth2.0哪种方式获取Access Token,都会拿到一个有效期为1个月的Access Token和有效期为2个月 的Refresh Token。对于这些应用,只要用户在两个月内登录,应用就可以使用Refresh Token刷新以获得新的 Access Token(新的Refresh Token也会同时下发),因此用户只要在两个月内登录过你的应用,就不需要重新登录。

流程示意

获取Access Token

http://openapi.tyread.com/oauth/token

使用Refresh Token刷新以获得新的Access Token,需要应用在其服务端发送请求(推荐用POST方法)到开放平台OAuth2.0授权服务的地址上,并带上以下参数

请求数据包格式

参数名

必选

说明

grant_type

True

固定为“refresh_token”

refresh_token

True

用于刷新Access Token用的Refresh Token

client_id

True

应用的API Key

client_secret

True

应用的Secret Key

scope

False

以 空格分隔的权限列表,若不传递此参数,代表请求的数据访问操作权限与上次获取Access Token时一致。通过Refresh Token刷新 Access Token时所要求的scope权限范围必须小于等于上次获取Access Token时授予的权限范围,详细请参考权限列表

响应数据包格式

若参数无误,服务器将返回一段JSON文本,包含以下参数:

 

参数名

说明

access_token

要获取新的Access Token

expires_in

Access Token的有效期,以秒为单位

refresh_token

用于刷新Access Token 的 Refresh Token

scope

Access Token最终的访问范围,即用户实际授予的权限列表

 

若请求错误,服务器将返回一段JSON文本,包含以下参数:

 

参数名

说明

error_code

错误码

error

错误说明

request

\/oauth2\/access_token

 

 

权限列表

结构定义

结构体名称(结构体中文说明)

说明:“请求标识”有“无”的均为get请求,有对象标识的为Post请求,并且有标识符不为空的,可以链接到接口的方法中。响应的标识为响应报文的结构体。

1.1用户登陆和注册类

请求标识

请求类型

响应标识

响应类型

Api列表

备注

user_register

request

User_reg_res

response

ctwap_register

CTWAP注册接口

User_login

request

User_log_res

response

ctwap_login

CTWAP登录接口

User_register

request

User_reg_res

response

account_register

普通注册接口

User_login

request

User_log_res

response

account_login

普通登陆接口

User_pass

request

User_pass_res

response

reset_password

修改密码接口

Get请求

User_info_res

response

query_userinfo

获取用户信息接口

User_info

request

User_info_res

response

update_userinfo

修改用户信息接口

Get请求

User_order_res

response

query_user_order_list

获取登录用户订购内容接口

1.2分栏和频道类

请求标识

请求类型

响应标识

响应类型

Api列表

备注

request

channel_list

response

query_channel_content_list

获取频道下内容列表信息接口;channel_list下有n个content_info节点

request

Channel_info

response

query_channel_info

获取频道信息接口

request

Channel_info

response

query_channel_catalog

获取频道下分栏信息接口;Channel_info节点下有N个catalog_info节点

request

Catalog_info

response

query_catalog_content_list

获取分栏下内容列表信息接口;Catalog_info下有N个content_info节点

request

Catalog_info

response

query_catalog_info

获取分栏信息接口

1.3排行推荐类

请求标识

请求类型

响应标识

响应类型

Api列表

备注

request

rank_info

response

query_rank_info

获取排行基本信息接口

request

rank_info

response

query_rank_list

获取排行下的内容列表接口; Rank_info下有N个content_info节点

request

rank_info

response

get_rank_channel_list

指定分栏所被绑定的排行

request

rank_info

response

get_rank_catalog_list

指定分栏所被绑定的排行

1.4章节内容类

请求标识

请求类型

响应标识

响应类型

Api列表

备注

request

image_info

response

get_content_cover

获取内容封面接口

request

content_info

response

get_content_desc

获取内容推荐描述接口

request

content_info

response

get_base_content

获取内容基本信息接口

request

content_info

response

get_content_type

获取内容类型接口

request

author_info

response

get_author_by_contentid

获取内容作者信息接口

request

ceb_info

response

get_ceb_by_contentid

获取内容CEB信息接口

request

volume_info

response

get_volume_list

获取内容卷列表接口

request

chapter_info

response

get_chapter_by_volumeid

1.1.25 通过卷ID获取内容章节列表接口

request

chapter_info

response

get_book_chapter_list

获取内容目录列表接口

request

content_info

response

get_description_content

获取内容简介信息接口

request

channel_info

response

get_channel_name

获取内容所在频道接口

request

chapter_list

response

get_chapter_info_list

获取内容章节列表接口; Chapter_list下面是N个chapter_info

request

chapter_info

response

get_chapter_info

获取内容章节信息接口

1.5书签类

请求标识

请求类型

响应标识

响应类型

Api列表

备注

request

system_mark_list

response

get_system_bookmark

获取系统书签接口;User_mark_ list下面是N个System_mark_list

add_system_info

Request

system_mark_ info

response

add_system_bookmark

增加系统书签接口

request

system_mark_ info

response

delete_all_system_bookmark

删除用户的所有系统书签接口

add_user_info

request

user_mark_ info

response

add_user_bookmark

增加用户的用户书签接口

request

user_mark_ info

response

delete_all_user_bookmark

删除用户的所有用户书签

request

user_mark_ list

response

get_all_user_bookmark

获取用户的用户书签; User_mark_ list下面是N个content_info

request

bookmark_ info

response

delete_bookmark_by_id

删除指定的书签

request

bookmark_ list

response

get_bookmark_by_contentid

获取内容书签

Off_mark

request

offmark_ info

response

add_offline_bookmark

增加离线书签

request

offmark_ info

response

delete_offline_bookmark_by_id

删除离线书签

1.6专题专区类

请求标识

请求类型

响应标识

响应类型

Api列表

备注

request

topic_list

response

get_subject_list

获取所有专题列表

request

topic_info

response

get_subject_detail

获取专题详情

request

topic_list

response

get_subject_sub_catalog

获取专题子分类; Topic_list下有N个topic_info

request

subtopic_list

response

get_subject_content

获取专题下内容; Subtopic_list下有N个content_info

request

zone_list

response

get_special_catalog_list

获取指定专区内容列表; Zone_list下有N个content_info

content_list

request

recommend_list

response

get_catalog_by_contentids

获取内容所在分栏的推荐列表

request

free_zone_list

response

get_all_free_content

获取免费专区下的所有书籍; Free_zone_list下面有N个content_info

request

free_recommend_list

response

get_recomment_free _content

获取免费专区下的推荐书籍; Free_recommend_list下面有N个content_info

1.7包月订购类

请求标识

请求类型

响应标识

响应类型

Api列表

备注

request

product_info

response

renewal_monthproduct

包月续费接口

request

product_info

response

unsubscribe_packproduct_readpoint

阅点包月退订

request

sso_product_info

response

unsubscribe_packproduct_sso

sso包月退订

request

order_info

response

is_content_ordered

判断内容或章节是否被订购

request

order_info

response

is_monthproduct_ordered

判断包月产品是否被订购

request

product_info

response

get_monthproduct_by_id

获取指定的包月产品信息;

request

product_info

response

get_product_by_contentid

获取内容所在包月产品的信息

request

product_info

response

get_product_by_outid

获取外部计费点对应的包月产品信息

request

product_list

response

get_booklist_by_pid

获取包月产品下的内容列表;Product_list下面有N个content_info

request

fee_info

response

get_productfee_by_contentid

获取内容内部计费点的信息

request

price_info

response

get_productprice_by_contentid

获取内容的产品价格信息

request

fee_info

response

get_outproduct_by_contentid

获取内容的外部计费点信息

request

image_info

response

get_platform_image

获取平台其他封面接口