Skip to content

Latest commit

 

History

History
378 lines (323 loc) · 6.81 KB

v1.md

File metadata and controls

378 lines (323 loc) · 6.81 KB

BlogReaper.Docs

[TOC]

Override

BlogReaper API v1使用GraphQL设计，其Schema在此页面。

API分为Query和Mutation两类，其中Query负责数据查询，Mutation负责数据增删改和权限管理。BlogReaper不采用Subscription类型API。

Authentication

BlogReaper关于权限管理的API仅有3个，分别为createLoginUrl、login、logout。

createLoginUrl

type Mutation {
    # createLoginUrl
    #
    # @params:
    #   backUrl - 回调地址，登录之前所处的地址，用于登录成功后跳转回去
    # @returns:
    #   String! - 登录地址，可能为空
    createLoginUrl(backUrl: String!): String!
}

login

type Mutation {
    # login
    #
    # @params:
    #   code - 由紫罗兰返回的用户code，可通过Sdk获取用户token
    #   state - 随机数，防止CSRF攻击
    # @returns:
    #   User - 用户信息
    # @errors:
    #   error_state - 状态数错误
    #   violet_error - 从紫罗兰获取数据错误
    #   initial_fail - 初始化用户失败
    login(code: String!, state: String!): User
}

logout

type Mutation {
    # logout
    #
    # @returns:
    #   Boolean - 是否注销成功
    logout: Boolean!
}

Query

BlogReaper提供4个查询的API。

feeds

type Query {
    # feeds
    #
    # @returns:
    #   []Feed - 订阅源
    # @errors:
    #   empty_keyword - 关键词为空
    feeds(keyword: String!): [Feed!]!
}

popularFeeds

type Query {
    # popularFeeds
    #
    # @params:
    #   page - 页数
    #   numPerPage - 每页订阅源数
    # @returns:
    #   []Feed - 筛选得到的订阅源
    # @errors:
    #   invalid_params - 参数错误
    popularFeeds(page: Int!, numPerPage: Int!): [Feed!]!
}

popularArticles

type Query {
    # popularArticles
    #
    # @params:
    #   page - 页数
    #   numPerPage - 每页文章数
    # @returns:
    #   []Feed - 筛选得到的文章
    popularArticles(page: Int!, numPerPage: Int!): [Article!]!
}

user

type Query {
    # user
    #
    # @returns:
    #   User - 用户信息
    # @errors:
    #   not_login - 未登录
    #   not_found - 找不到该用户
    user: User
}

Mutation

addCategory

type Mutation {
    # addCategory
    #
    # @params:
    #   name - 分类名字
    # @returns:
    #   Category - 分类
    # @errors:
    #   not_login - 未登录
    #   repeat_name - 重复分类名
    addCategory(name: String!): Category
}

addFeed

type Mutation {
    # addFeed
    #
    # @params:
    #   id - 订阅源Id
    #   categoryId - 分类Id
    # @returns:
    #   Feed - 订阅源
    # @errors:
    #   not_login - 未登录
    #   invalid_category - 分类不存在
    #   invalid_id - 订阅源不存在
    #   repeat_feed - 重复的订阅源
    addFeed(id: String!, categoryId: String!): Feed
}

addPublicFeedOrNot

type Mutation {
    # addPublicFeedOrNot
    #
    # @params:
    #   url - 订阅的链接(不得以'/'结尾，以'http'或'https'开头)
    # @returns:
    #   Feed - 订阅源
    # @errors:
    #   invalid_url - 订阅源不存在
    addPublicFeedOrNot(url: String!): Feed
}

editArticle

type Mutation {
    # editArticle
    #
    # @params:
    #   url - 文章链接
    #   feedId - 订阅源Id
    #   read - 标记已读或未读
    #   later - 标记稍后阅读或取消稍后阅读
    # @returns:
    #   Boolean - 是否成功修改文章
    # @errors:
    #   not_login - 未登录
    #   invalid_params - 参数错误
    #   invalid_feed_or_url - 订阅源id或url非法
    editArticle(url: String!, feedId: String!, read: Boolean, later: Boolean): Boolean!
}

editCategory

type Mutation {
    # editCategory
    #
    # @params:
    #   id - 分类Id
    #   name - 分类的新名字
    # @returns:
    #   Boolean - 是否更改成功
    # @errors:
    #   not_login - 未登录
    #   invalid_id - 分类不存在
    editCategory(id: String!, name: String!): Boolean!
}

editFeed

type Mutation {
    # editFeed
    #
    # @params:
    #   id - 订阅源的id
    #   title - 更新的标题
    #   categoryId - 传入的分类的id
    # @returns:
    #   Boolean - 是否修改成功
    # @errors:
    #   not_login - 未登录
    #   not_found - 阅读源不存在
    #   invalid_category - 分类不存在
    editFeed(id: String!, title: String, categoryIds: [String!]): Boolean!
}

removeCategory

type Mutation {
    # removeCategory
    #
    # @params:
    #   id - 分类的id
    # @returns:
    #   Boolean - 是否修改成功
    # @errors:
    #   not_login - 未登录
    #   not_found - 分类不存在
    removeCategory(id: String!): Boolean!
}

removeFeed

type Mutation {
    # removeFeed
    # 
    # @params:
    #   id - 订阅源的id
    # @returns:
    #   Boolean - 是否移除成功
    # @errors:
    #   not_login - 未登录
    #   not_found - 未找到记录
    removeFeed(id: String!): Boolean!
}

Object

Article

type Article {
    url: String!
    title: String!
    published: String!
    updated: String!
    content: String!
    summary: String!
    pictureUrl: String!
    categories: [String!]!
    read: Boolean!
    later: Boolean!
    feedId: String!
    feedTitle: String!
}

Category

type Category {
    id: String!
    name: String!

    # feeds
    #
    # @params:
    #   id - 订阅源Id
    # @returns:
    #   []Feed - 订阅源
    # @errors:
    #   not_login - 未登录
    #   invalid_id - 分类不存在
    feeds(id: String): [Feed!]!
}

Feed

type Feed {
    id: String!
    publicId: String!
    url: String!
    title: String!
    subtitle: String!
    follow: Int!
    articlesNumber: Int!

    # articles
    #
    # @params:
    #   page - 页数
    #   numPerPage - 每页文章数
    # @returns:
    #   []Article - 筛选得到的文章
    articles(page: Int, numPerPage: Int): [Article!]!
}

User

type User {
    email: String!
    info: UserInfo!

    # categories
    #
    # @params:
    #   id - 分类Id
    # @returns:
    #   []Category - 分类
    # @errors:
    #   not_login - 未登录
    categories(id: String): [Category!]!

    # laterArticles
    #
    # @params:
    #   page - 页数
    #   numPerPage - 每页文章数
    # @returns:
    #   []Article - 筛选得到的文章
    # @errors:
    #   not_login - 未登录
    #   invalid_params - 参数错误
    laterArticles(page: Int, numPerPage: Int): [Article!]!
}

UserInfo

type UserInfo {
    name: String!
    avatar: String!
    bio: String!
    gender: Int!
}