为什么要用Json api/Graph api

场景：

ie:Link
想像一个场景, 制作一个文章发布平台 , 需要添加评论(评论数多,还要做分页) 和点赞功能.

Restful 解决方案：

1. 增加api的数量 获取评论api， 获取点赞数api

2. 更改原来的api 增加 评论，点赞

REST 的缺点

1. 多次查询 论坛程序 查询一篇文章以及下面的评论 可能需要两次查询 即 一次对博文资源的获取，一次对评论的获取，

2. 资源过度获取 rest 由于一个接口对应一个资源，很容易造成， 一次查询不足， 二次查询的时候 调用相同信息，或者返回很多不必要的信息，造成网络资源浪费

3. API 版本控制,restful 新版本 api 测试阶段， 老版本 api 不能停用， 于是造成很多重复代码

4. 弱类型, 对类型没有规定, 客户端容易解析错误

5. 可能需要二次协商, 前后端同时开发，造成返回类型不统一.

6. get 局限性. 只支持 2048 个字节，不支持传输 body，url 很容易很难看

JSON Api

设计概念： API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.

设计规范：

GET /articles?include=author HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z",
      "updated": "2015-05-22T14:56:28.000Z"
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John",
        "age": 80,
        "gender": "male"
      }
    }
  ]
}

• 排序

  GET /people?sort=age HTTP/1.1
  Accept: application/vnd.api+json

• 分页

1. request:

GET /articles?page[number]=3&page[size]=1 HTTP/1.1

2. response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "meta": {
    "totalPages": 13
  },
  "data": [
    {
      "type": "articles",
      "id": "3",
      "attributes": {
        "title": "JSON:API paints my bikeshed!",
        "body": "The shortest article. Ever.",
        "created": "2015-05-22T14:56:29.000Z",
        "updated": "2015-05-22T14:56:28.000Z"
      }
    }
  ],
  "links": {
    "self": "http://example.com/articles?page[number]=3&page[size]=1",
    "first": "http://example.com/articles?page[number]=1&page[size]=1",
    "prev": "http://example.com/articles?page[number]=2&page[size]=1",
    "next": "http://example.com/articles?page[number]=4&page[size]=1",
    "last": "http://example.com/articles?page[number]=13&page[size]=1"
  }
}

3. 关于feilds

   GET /articles?include=author&fields[articles]=title,body,author&fields[people]=name HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever."
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John"
      }
    }
  ]
}

4. error design:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json

{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "code":   "123",
      "source": { "pointer": "/data/attributes/firstName" },
      "title":  "Value is too short",
      "detail": "First name must contain at least three characters."
    },
    {
      "code":   "225",
      "source": { "pointer": "/data/attributes/password" },
      "title": "Passwords must contain a letter, number, and punctuation character.",
      "detail": "The password provided is missing a punctuation character."
    },
    {
      "code":   "226",
      "source": { "pointer": "/data/attributes/password" },
      "title": "Password and password confirmation do not match."
    }
  ]
}

GraphQL 接口设计

概念

graphQL 是一种 Query language, server-side 通过定义和解析 query 去查询，修改数据.主要是为了加快程序开发进度，减少前后端协商时间.

ref(Link)

流程：

例子: 查询已经登录的 user 和名字. 规定 types and fields

1. 定义接口服务

type Query {
  me: User
}

type User {
  id: ID
  name: String
}

function Query_me(request) {
    //其他逻辑
  return request.auth.user;
}

function User_name(user) {
    // 其他逻辑
  return user.getName();
}

2. 通过 Graph QL 解析

发出请求：

GET /graphql?query={me{name}}

{
  me {
    name
  }
}

得到结果：

{
  "me": {
    "name": "Luke Skywalker"
  }
}

POST 请求

POST /graphql
{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

{
  "data": { ... },
  "errors": [ ... ]
}

设计规范

ref:Link

GraphQL 缺点

1. 检测和错误报告, 由于 api 统统都走一个端口， 返回值永远是 200，即使服务端错误

2. 缺乏很好的原生 安全和验证机制

3. 暴露资源,接口一但暴露, 很容易造成整体瘫痪

4. 社区小, 生态少

ref(Link)

refrence：

ref:(Link)

ref:(Link)

---

json API client side caching