API Reference

Wallpapers 4K HD Backend API Reference

介绍

本文描述了 Wallpapers 4K HD 后端 API 的基本使用情况。

访问基础

所有向后端发起的 API 请求的基准 URL 为 https://wallpapers4khd.avividapps.com/api。

版本

API 版本号紧随 API 基准 URL 之后 https://wallpapers4khd.avividapps.com/api/<version>，目前最新版本为 v1。

API Endpoints

用户 API

通过邮箱创建用户

Type	End
POST	/accounts/

参数

Name	Type	Required?	Description	Default
email	字符串	是	用户邮箱，需唯一
password1	字符串	是	密码大小写加符号
password2	字符串	是	验证密码，避免用户输入错误

例子

http://wallpapers4khd.avividapps.com/api/v1/accounts/

调用该接口会处罚验证邮件的发送，用于验证用户输入的 Email 地址是否为真实 Email 地址，如果验证邮件发送成功，会收到如下 Response

{
    "detail": "Verification e-mail sent."
}

此时会收到一个包含六位验证码的邮件，客户端需要 Launch 一个页面提供用户输入六位验证码，然后带上验证码访问下面的接口

验证用户邮箱

Type	End
POST	/accounts/verify/

参数

Name	Type	Required?	Description	Default
key	字符串	是	密码大小写加符号

当用户邮箱验证成功，会收到如下 Response

{
	"detail": "ok"
}

只有 Email 地址验证通过后，用户才能够使用下面的邮箱登录 API 获取 Access Token

通过邮箱登录

Type	End
POST	/auth/login

参数

Name	Type	Required?	Description	Default
email	字符串	是	用户邮箱，需唯一
password	字符串	是	用户密码

例子

http://wallpapers4khd.avividapps.com/api/v1/auth/login/

如果用户登录成功，会返回如下 Response

{
		"access": "<access token>",
		"refresh": "<refresh token>",
		"user": {
		  "uuid": "<user uuid>"
		}
}

Token 的过期和刷新

客户端应当在本地保存 Access Token 和 Refresh Token, 当遇到需要用户 认证才能访问的 API 时，需要在 Header 中添加 Authorization 字段，并将 Access Token 放在其中，形如

Header 字段名：Authorization

Header 值：Bearer

当 Access Token 访问失败时可以尝试用 Refresh Token 调用下面的接口获取新的 Access Token

更新 Access Token

Type	End
POST	/auth/token/refresh

参数

Name	Type	Required?	Description	Default
refresh	字符串	是	Refresh Token

的作用

建议客户端在登录成功后将 保存在本地，因此客户端可以在 IAP 调用时传递此 , Apple 会在调用服务器端的回调 API 时在 Payload 中包含此 uuid, 这是目前本系统唯一识别 IAP 发起账户的方式

获取用户信息

Type	End
GET	/user/profile/

Header

Name	Type	Required?	Description
Authorization	字符串	是	认证用户的信息 ，形式如：Bearer

如果用户认证信息正确，则可以返回如下用户信息 Response

{
	"email": "<email address>",
	"nickname": "<nickname>",
	"gender": "M" | "F",
	"uuid": "<user uuid>"
	"avatar": "<user avatar url>"
	"receipts": [
		{ <receipt data> },
		{ <receipt data> },
		...
	]
}

修改用户信息

Type	End
PUT	/user/profile/

Header

Name	Type	Required?	Description
Authorization	字符串	是	认证用户的信息 ，形式如：Bearer

参数

Name	Type	Required?	Description	Default
nickname	字符串	否	用户昵称
gender	字符串	否	用户 性别
avatar	字符串	否	用户头像地址

如果用户认证信息正确, 并且用户信息修改成功，则可以返回如下用户信息 Response，其他从 Profile GET 请求中获取的字段，如 uuid, email 和 receipts 是无法修改的

{
	"nickname": "<nickname>",
	"gender": "M" | "F",
	"avatar": "<user avatar url>"
}

用户收藏

Type	End
GET	/user/favorites/

Header

Name	Type	Required?	Description
Authorization	字符串	是	认证用户的信息 ，形式如：Bearer

参数

Name	Type	Required?	Description	Default
type	字符串	否	可选的值有三个 wallaper, avatar 或 emoji	wallpaper

💡 目前该接口暂不提供分页功能

通过 Instagram 登录

Type	End
POST	/auth/instagram

参数

Name	Type	Required?	Description	Default
access_token	字符串	否	OAuth 流程中的 Access Token

例子

http://wallpapers4khd.avividapps.com/api/v1/auth/instagram/

说明

客户端需要参考该文档实现 Instagram 的 Authorization Window

https://developers.facebook.com/docs/instagram-basic-display-api/overview#authorization-window

将此 API 作为 redirect_uri 传递给 Authorization Window

通过 Apple ID 登录

Type	End
POST	/auth/apple

参数

Name	Type	Required?	Description	Default
access_token	字符串	是	Sign In with Apple 中返回的 authorizationCode
id_token	字符串	是	Sign In with Apple 中返回的 identityToken

例子

http://wallpapers4khd.avividapps.com/api/v1/auth/apple/

说明

客户端需要参考该文档实现 Instagram 的 Authorization Window

https://developers.facebook.com/docs/instagram-basic-display-api/overview#authorization-window

将此 API 作为 redirect_uri 传递给 Authorization Window

内容 API

获取 Wallpaper Category 列表

Type	PATH
GET	/apps/{app_id}/categories?lang={language}

参数

Name	Type	Required?	Description	Default
app_id	数字	是	w103 后台中 app 的 id 的值
language	字符串	否	客户端语言，目前支持 zh-Hans 和 en	zh-Hans
version

例子

http://wallpapers4khd.avividapps.com/api/v1/apps/7/categories?lang=zh-Hans

获取 Wallpaper Category 内容

Type	PATH
GET	/apps/apps/{app_id}/categories/{category_id}?lang={language}&size={size}&per_page={page_size}&page={page}

参数

Name	Type	Required?	Description	Default
app_id	数字	是	w103 后台中 app 的 id 的值
category_id	数字	是	w103 后台中 category 的 id 的值
language	字符串	否	客户端语言，目前支持 zh-Hans 和 en	zh-Hans
size	数字	否	设备的屏幕大小规格	5
page_size	数字	否	每页内容的最大数量	27
page	数字	否	当前请求的为第几页内容	1

示例

http://wallpapers4khd.avividapps.com/api/v1/apps/7/categories/25?size=5sort=recent&lang=zh-Hans&per_page=50&page=1

记录用户对 Wallpaper 的操作

Type	PATH
POST	/wallpapers/{wallpaper_id}/{action}

Header

Name	Type	Required?	Description
Authorization	字符串	否	认证用户的信息 ，形式如：Bearer

💡 如果 action 为 fav 但是为带 Authorization Header, 将得到 403 限制访问

参数

Name	Type	Required?	Description	Default
wallpaper_id	数字	是	要记录用户对其操作的 wallpaper 的 id
action	字符串	是	用户操作 view, save, share, fav 的其中之一

示例

http://wallpapers4khd.avividapps.com/api/v1/wallpapers/100/fav

获取 Avatar Category 列表

Type	PATH
GET	/apps/{app_id}/avatarcategories?lang={language}

参数

Name	Type	Required?	Description	Default
app_id	数字	是	w103 后台中 app 的 id 的值
language	字符串	否	客户端语言，目前支持 zh-Hans 和 en	zh-Hans

示例

http://wallpapers4khd.avividapps.com/api/v1/apps/7/avatarcategories?lang=zh-Hans

获取 Avatar Category 内容

Type	PATH
GET	/apps/{app_id}/avatarcategories/{category_id}?lang={language}&size={size}&per_page={page_size}&page={page}

参数

Name	Type	Required?	Description	Default
app_id	数字	是	w103 后台中 app 的 id 的值
category_id	数字	是	w103 后台中 category 的 id 的值
language	字符串	否	客户端语言，目前支持 zh-Hans 和 en	zh-Hans
size	数字	否	设备的屏幕大小规格	5
page_size	数字	否	每页内容的最大数量	27
page	数字	否	当前请求的为第几页内容	1

示例

http://wallpapers4khd.avividapps.com/api/v1/apps/7/avatarcategories/25?sort=recent&lang=zh-Hans&per_page=27&page=1

记录用户对 Avatar 的操作

Type	PATH
POST	/avatars/{avatar_id}/{action}

Header

Name	Type	Required?	Description
Authorization	字符串	否	认证用户的信息 ，形式如：Bearer

💡 如果 action 为 fav 但是为带 Authorization Header, 将得到 403 限制访问

参数

Name	Type	Required?	Description	Default
avatar_id	数字	是	需要操作的 avatar 的 id
action	字符串	是	对 avatar 的 操作 view, save, share, fav 之一

示例

http://wallpapers4khd.avividapps.com/api/v1/avatars/100/fav

获取 Emoji Category 列表

Type	PATH
GET	/apps/{app_id}/emojicategories?lang={language}

参数

Name	Type	Required?	Description	Default
app_id	数字	是	w103 后台中 app 的 id 的值
language	字符串	否	客户端语言，目前支持 zh-Hans 和 en	zh-Hans

示例

http://wallpapers4khd.avividapps.com/api/v1/apps/7/emojicategories?lang=zh-Hans

获取 Emoji Category 内容

Type	PATH
GET	/apps/{app_id}/emojicategories/{category_id}?lang={language}&size={size}&per_page={page_size}&page={page}

参数

Name	Type	Required?	Description	Default
app_id	数字	是	w103 后台中 app 的 id 的值
category_id	数字	是	w103 后台中 category 的 id 的值
language	字符串	否	客户端语言，目前支持 zh-Hans 和 en	zh-Hans
size	数字	否	设备的屏幕大小规格	5
page_size	数字	否	每页内容的最大数量	27
page	数字	否	当前请求的为第几页内容	1

示例

http://wallpapers4khd.avividapps.com/api/v1/apps/7/emojicategories/25?sort=recent&lang=zh-Hans&per_page=27&page=1

记录用户对 Emoji 的操作

Type	PATH
POST	/avatars/{emoji_id}/{action}

Header

Name	Type	Required?	Description
Authorization	字符串	否	认证用户的信息 ，形式如：Bearer

💡 如果 action 为 fav 但是为带 Authorization Header, 将得到 403 限制访问

参数

Name	Type	Required?	Description	Default
emoji_id	数字	是	需要操作的 emoji 的 id
action	字符串	是	对 avatar 的 操作 view, save, share, fav 之一

示例

http://wallpaper103.avividapps.com/api/v1/emojis/100/fav

搜索 Wallpaper，Avatar 或者 Emoji

Type	PATH
GET	apps/{app_id}/search?tags={tags}&type={type}

Header

Name	Type	Required?	Description
Authorization	字符串	否	认证用户的信息 ，形式如：Bearer

💡 如果搜索是不提供 Authorization，将返回普通内容，当提供了 Authorization 并且认证用户为 VIP 用户时，能够搜索到 VIP 内容

参数

Name	Type	Required?	Description	Default
app_id	数字	是	w103 后台中 app 的 id 的值
tags	字符串	是	要搜索的关键字，逗号分隔
type	字符串	可选	wallpaper, emoji, avatar 其中之一	wallpaper