moredoc/docs/api.md

Protocol Documentation

Table of Contents

• api/v1/attachment.proto

  • Attachment

  • DeleteAttachmentRequest

  • GetAttachmentRequest

  • ListAttachmentReply

  • ListAttachmentRequest

  • AttachmentAPI

• api/v1/banner.proto

  • Banner

  • DeleteBannerRequest

  • GetBannerRequest

  • ListBannerReply

  • ListBannerRequest

  • BannerAPI

• api/v1/config.proto

  • Config

  • Configs

  • ListConfigRequest

  • ConfigAPI

• api/v1/friendlink.proto

  • DeleteFriendlinkRequest

  • Friendlink

  • GetFriendlinkRequest

  • ListFriendlinkReply

  • ListFriendlinkRequest

  • FriendlinkAPI

• api/v1/group.proto

  • DeleteGroupRequest

  • GetGroupPermissionRequest

  • GetGroupRequest

  • Group

  • GroupPermissions

  • ListGroupReply

  • ListGroupRequest

  • UpdateGroupPermissionRequest

  • GroupAPI

• api/v1/health.proto

  • PingRequest

  • PongReply

  • HealthAPI

• api/v1/permission.proto

  • DeletePermissionRequest

  • GetPermissionReply

  • GetPermissionRequest

  • ListPermissionReply

  • ListPermissionRequest

  • Permission

  • PermissionAPI

• api/v1/user.proto

  • DeleteUserRequest

  • GetUserCaptchaReply

  • GetUserCaptchaRequest

  • GetUserPermissionsReply

  • GetUserRequest

  • ListUserReply

  • ListUserRequest

  • LoginReply

  • RegisterAndLoginRequest

  • UpdateUserPasswordRequest

  • User

  • UserAPI

• Scalar Value Types

Top

api/v1/attachment.proto

Attachment

Field	Type	Label	Description
id	int64
hash	string
user_id	int64
type_id	int64
type	int32
enable	bool
path	string
name	string
size	int64
width	int64
height	int64
ext	string
ip	string
username	string		用户名称
type_name	string		附件类型名称
description	string		附件描述、备注
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp

DeleteAttachmentRequest

Field	Type	Label	Description
id	int64	repeated

GetAttachmentRequest

Field	Type	Label	Description
id	int64

ListAttachmentReply

Field	Type	Label	Description
total	int64
attachment	Attachment	repeated

ListAttachmentRequest

Field	Type	Label	Description
page	int64
size	int64
wd	string		搜索关键字
enable	bool	repeated
user_id	int64	repeated	用户ID
type	int64	repeated	类型
ext	string		扩展名

AttachmentAPI

附件服务。只有管理员才有权限操作

Method Name	Request Type	Response Type	Description
UpdateAttachment	Attachment	.google.protobuf.Empty
DeleteAttachment	DeleteAttachmentRequest	.google.protobuf.Empty
GetAttachment	GetAttachmentRequest	Attachment
ListAttachment	ListAttachmentRequest	ListAttachmentReply

Top

api/v1/banner.proto

Banner

Field	Type	Label	Description
id	int64
title	string
path	string
sort	int32
enable	bool
type	int32
url	string
description	string
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp

DeleteBannerRequest

Field	Type	Label	Description
id	int64	repeated

GetBannerRequest

Field	Type	Label	Description
id	int64

ListBannerReply

Field	Type	Label	Description
total	int64
banner	Banner	repeated

ListBannerRequest

Field	Type	Label	Description
page	int64
size	int64
type	int32	repeated
enable	bool	repeated
wd	string

BannerAPI

Method Name	Request Type	Response Type	Description
CreateBanner	Banner	Banner
UpdateBanner	Banner	.google.protobuf.Empty
DeleteBanner	DeleteBannerRequest	.google.protobuf.Empty
GetBanner	GetBannerRequest	Banner
ListBanner	ListBannerRequest	ListBannerReply

Top

api/v1/config.proto

Config

Field	Type	Label	Description
id	int64
label	string
name	string
value	string
placeholder	string
input_type	string
category	string
sort	int32
options	string
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp

Configs

Field	Type	Label	Description
config	Config	repeated

ListConfigRequest

Field	Type	Label	Description
category	string	repeated

ConfigAPI

Method Name	Request Type	Response Type	Description
UpdateConfig	Configs	.google.protobuf.Empty	UpdateConfig 更新配置
ListConfig	ListConfigRequest	Configs	ListConfig 查询配置项

Top

api/v1/friendlink.proto

DeleteFriendlinkRequest

Field	Type	Label	Description
id	int64	repeated

Friendlink

Field	Type	Label	Description
id	int32
title	string
link	string
description	string
sort	int32
enable	bool
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp

GetFriendlinkRequest

Field	Type	Label	Description
id	int64

ListFriendlinkReply

Field	Type	Label	Description
friendlink	Friendlink	repeated
total	int64

ListFriendlinkRequest

Field	Type	Label	Description
page	int32
size	int32
wd	string
enable	bool	repeated

FriendlinkAPI

Method Name	Request Type	Response Type	Description
CreateFriendlink	Friendlink	Friendlink
UpdateFriendlink	Friendlink	.google.protobuf.Empty
DeleteFriendlink	DeleteFriendlinkRequest	.google.protobuf.Empty
GetFriendlink	GetFriendlinkRequest	Friendlink
ListFriendlink	ListFriendlinkRequest	ListFriendlinkReply

Top

api/v1/group.proto

DeleteGroupRequest

Field	Type	Label	Description
id	int64	repeated

GetGroupPermissionRequest

Field	Type	Label	Description
id	int64

GetGroupRequest

根据组名或者ID获取用户组

Field	Type	Label	Description
id	int64
title	string

Group

Field	Type	Label	Description
id	int64
title	string
color	string
is_default	bool
is_display	bool
description	string
user_count	int32
sort	int32
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp

GroupPermissions

Field	Type	Label	Description
permission_id	int64	repeated

ListGroupReply

Field	Type	Label	Description
group	Group	repeated
total	int64

ListGroupRequest

查询用户组列表。不需要分页，直接返回全部用户组，只是可以指定查询哪些字段

Field	Type	Label	Description
wd	string
page	int64
size	int64
sort	string
field	string	repeated

UpdateGroupPermissionRequest

Field	Type	Label	Description
group_id	int64
permission_id	int64	repeated

GroupAPI

Method Name	Request Type	Response Type	Description
CreateGroup	Group	Group	创建用户组
UpdateGroup	Group	.google.protobuf.Empty	更新用户组
DeleteGroup	DeleteGroupRequest	.google.protobuf.Empty	删除用户组
GetGroup	GetGroupRequest	Group	获取用户组列表
ListGroup	ListGroupRequest	ListGroupReply
GetGroupPermission	GetGroupPermissionRequest	GroupPermissions	获取用户组权限列表
UpdateGroupPermission	UpdateGroupPermissionRequest	.google.protobuf.Empty	更新用户组权限，给用户组设置权限

Top

api/v1/health.proto

PingRequest

Field	Type	Label	Description
name	string

PongReply

Field	Type	Label	Description
name	string
created_at	google.protobuf.Timestamp

HealthAPI

Method Name	Request Type	Response Type	Description
Health	.google.protobuf.Empty	.google.protobuf.Empty
Ping	.PingRequest	.PongReply

Top

api/v1/permission.proto

DeletePermissionRequest

Field	Type	Label	Description
id	int64	repeated

GetPermissionReply

Field	Type	Label	Description
permission	Permission

GetPermissionRequest

Field	Type	Label	Description
id	int64

ListPermissionReply

Field	Type	Label	Description
total	int64
permission	Permission	repeated

ListPermissionRequest

Field	Type	Label	Description
page	int64
size	int64
wd	string
method	string	repeated
path	string

Permission

Field	Type	Label	Description
id	int64
method	string
path	string
title	string
description	string
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp

PermissionAPI

Method Name	Request Type	Response Type	Description
UpdatePermission	Permission	.google.protobuf.Empty
GetPermission	GetPermissionRequest	Permission
ListPermission	ListPermissionRequest	ListPermissionReply

Top

api/v1/user.proto

DeleteUserRequest

Field	Type	Label	Description
id	int64	repeated

GetUserCaptchaReply

Field	Type	Label	Description
enable	bool
id	string
captcha	string
type	string

GetUserCaptchaRequest

Field	Type	Label	Description
type	string		验证码类型：register、login、comment、find_password、upload

GetUserPermissionsReply

Field	Type	Label	Description
permission	Permission	repeated

GetUserRequest

Field	Type	Label	Description
id	int64

ListUserReply

Field	Type	Label	Description
total	int64
user	User	repeated

ListUserRequest

Field	Type	Label	Description
page	int64
size	int64
wd	string
sort	string
id	int64	repeated
group_id	int64	repeated
status	int32	repeated

LoginReply

Field	Type	Label	Description
token	string
user	User

RegisterAndLoginRequest

Field	Type	Label	Description
username	string
password	string
captcha	string
captcha_id	string

UpdateUserPasswordRequest

修改用户密码

Field	Type	Label	Description
id	int64
old_password	string
new_password	string

User

Field	Type	Label	Description
login_at	google.protobuf.Timestamp
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp
id	int64
username	string
mobile	string
email	string
address	string
signature	string
last_login_ip	string
register_ip	string
doc_count	int32
follow_count	int32
fans_count	int32
favorite_count	int32
comment_count	int32
status	int32
avatar	string
identity	string
realname	string
group_id	int64	repeated

UserAPI

Method Name	Request Type	Response Type	Description
Register	RegisterAndLoginRequest	.google.protobuf.Empty	用户注册
Login	RegisterAndLoginRequest	LoginReply	用户登录
Logout	.google.protobuf.Empty	.google.protobuf.Empty	退出登录
GetUser	GetUserRequest	User	查询用户信息。如果传递了Id参数，则表示查询用户的公开信息，否则查询当前用户的私有信息
UpdateUserPassword	UpdateUserPasswordRequest	.google.protobuf.Empty	更新用户密码。如果不传用户ID，则表示更新当前用户的密码； 如果穿了用户ID，则表示更新指定用户的密码，这时需要验证当前用户的权限
UpdateUser	User	.google.protobuf.Empty	更新用户密码。如果不传用户ID，则表示更新当前用户的密码； 如果穿了用户ID，则表示更新指定用户的密码，这时需要验证当前用户的权限
DeleteUser	DeleteUserRequest	.google.protobuf.Empty	删除用户。需要验证用户权限
ListUser	ListUserRequest	ListUserReply	查询用户列表。对于非管理员，返回相应用户的公开信息； 对于管理员，返回相应用户的绝大部分信息
GetUserCaptcha	GetUserCaptchaRequest	GetUserCaptchaReply	GetUserCaptcha 获取用户验证码
GetUserPermissions	.google.protobuf.Empty	GetUserPermissionsReply	GetUserCaptcha 获取用户验证码

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)