核心接口

简介

一言核心接口是萌创团队在开发过程中，暴露给外部环境，方便开发的系列接口。它们实现了：

• 用户操作
• 句子操作
• 评分操作
• 举报操作

的功能。目前，这些接口可通过无状态模型使用。

接口地址

核心接口实现了两套认证机制，分别对应两个入口：

• 无状态服务： https://hitokoto.cn/api/restful/v1
• 会话认证：https://hitokoto.cn/api/common/v1

基于会话认证的接口的最初目的是便于前端调用，因此具备 CSRF 验证，不适合开发者使用。

约束

接下来，我们便以 无状态 接口作为入口进行讲解。

认证方式

无状态服务通过令牌（token）认证，因此每个需要验权的接口，其请求必须包含 token 字段。 目前支持三种验证方式：

• 请求参数，形如： ?token=xxxxx
• POST 参数（表单），例如：在 POST 表单中添加 <input type="hidden" name="token" value="xxxx" >
• bearer 授权

返回约束

返回结构以方便，可快捷测试，方便检验为目标。以下为参数的约束：

下面是一个示例： GET https://hitokoto.cn/api/restful/v1/hitokoto/62c12303-b3fa-4720-a7c5-2985bf049e60?token=xxx

{
  "status": 200,
  "message": "ok.",
  "data": [
    {
      "hitokoto": "过去都是假的，回忆是一条没有归途的路，以往的一切春天都无法复原，即使最狂热最坚贞的爱情，归根结底也不过是一种瞬息即逝的现实，唯有孤独永恒。",
      "uuid": "62c12303-b3fa-4720-a7c5-2985bf049e60",
      "type": "d",
      "from": "百年孤独",
      "from_who": null,
      "creator": "戎歌",
      "creator_uid": 1195,
      "reviewer": 0,
      "commit_from": "web",
      "created_at": "1532672964",
      "status": "accept"
    }
  ],
  "ts": 1582053586728
}

请注意: 接口会尽量使 HTTP 状态码为 200，但是由于上游中间件的问题，会出现 HTTP 不为 200 的情况，需要开发者自行处理。

接口方法

本节将提供目前暴露的接口表，方便快速查询。

请求头请添加 Accept: application/json 以保证接口输出一定是 JSON。
由于 Laravel 底层对 PUT 方法的支持不好，提交 PUT 参数时一定要以 x-www-form-urlencoded 方法提交参数。
或者，你可以使用 POST 方法，额外添加一个字段 _method: "PUT" 模拟 PUT 请求。

用户部分