带有JSON的REST API

什么是REST API？

REST代表重新表象小号大老贸易交接。 它依赖于无状态的客户端-服务器可缓存通信。 在大多数情况下，它与HTTP协议一起使用。

RESTful应用程序使用HTTP请求进行POST（创建），PUT（创建和/或更新），GET（例如，进行查询）和DELETE数据。 REST对所有四个CRUD（创建/读取/更新/删除）操作都使用HTTP。

什么是JSON？

JSON（JavaScript对象表示法）是一种轻量级的数据交换格式。 人类易于阅读和书写。 机器很容易解析和生成。

通讯协定

HTTP允许将不同的协议用于客户端和服务器之间的通信。 除了最常用的四种：GET，PUT，POST和DELETE，我们将不对所有这些进行解释。

GET，PUT和DELETE应该作为幂等方法实现。 无论重复请求多少次，结果都应该相同。 另一方面，POST不应是幂等的。

得到

GET执行某种查询。 它不要求以任何形式或方式对系统状态进行任何更改。 这并不意味着服务器没有对其状态进行任何更改，而是客户端没有请求它。 执行GET请求时，服务器应以JSON形式响应结果。

开机自检

POST是创建新实体的请求。 该实体的内容应包含在请求正文中。

放

PUT与POST类似，不同之处在于，如果一个实体不存在，则它应该创建一个新实体，或者修改现有实体。

删除

DELETE是从服务器删除指定实体的请求。

向服务器的请求

避免使用诸如getAllBooks或createNewBook之类的非名词。 使用HTTP方法GET，POST，PUT和DELETE指定要执行的操作的类型。 URI应该指定要对其执行操作的实体。 例如， GET / books应该从服务器检索书籍， DELETE / books应该删除书籍， PUT / books应该修改或创建书籍，而POST / book应该请求在服务器中创建书籍。

如果是GET方法，则URI的其余部分应提供有关查询服务器类型的信息，查询服务器应使用该类型来检索请求的数据。 在URI本身内使用查询参数。 例如， / books应该返回所有书籍。 / books / id / 24应该返回ID为24的图书。/books/pageSize/25应该仅返回25本图书。

其余方法（POST，PUT和DELETE）应将所有信息以JSON格式包含在消息正文中。

与GET方法类似，DELETE可能适用于一个特定数据，数据子集或全部（如果服务器允许）。 如果要删除一本书，则DELETE / book请求的主体中将带有JSON {id：24} 。 同样，如果要删除符合更广泛标准的图书，则JSON为{author：'Viktor Farcic'} 。 最后，如果没有正文，则将删除所有书籍。

POST和PUT以类似DELETE的方式工作。 他们的请求主体具有应创建或修改的信息。 可以将单个实体放入请求PUT / books的主体中。 该请求将创建或修改一本书。 一个示例可以是{id：12345，标题：“行为驱动的开发”，作者：“ Viktor Farcic”} 。 如果允许批量插入，则可以将多个实体作为数组传递[{title：'行为驱动开发，作者：'Viktor Farcic'}，{title：'Continuous Integration'，作者：'Viktor Farcic'}] 。

请记住，服务器负责验证是否允许某些请求。 删除多于一本书的操作只能限于某些用户，而对于所有用户，可以拒绝不带正文的DELETE请求（全部删除）。 决定是否允许请求的最终责任在于服务器。

总而言之，GET没有正文，而是使用URI来指定实体（即/ books），并在需要时指定其他查询参数（即id / 24）。 POST，PUT和DELETE不应通过URI指定查询参数，而应使用消息正文传递有关应创建，修改或删除内容的信息。

来自服务器的响应

来自服务器的响应应始终为JSON格式且保持一致。 它们应始终包含元信息和（可选）数据。 一致性使我们的API使用者可以知道期望什么。 而且，由于可以对所有请求类型以统一的方式执行某些解析，因此它使我们可以编写更少的实现代码。

HTTP响应已经包含状态（有关状态代码的更多信息，请参见“ 状态代码定义” ）。 通过元信息可以包含其他信息，我们可以增强它。 特定于服务器中实现的附加信息可以提供，例如，错误和消息。 通常，当客户端收到HTTP状态为2XX的响应时，请求成功。 状态为4XX的响应表示客户端引发的错误（即缺少必需数据），状态为5XX的响应是服务器错误。

即使没有从服务器发送数据，也应指定数据 。

几个例子是：

{
  meta: {
  },
  data: {
    id: 24,
    title: 'Behavior-Driven Development',
    author: 'Viktor Farcic'
  }
}

{
  meta: {
    error: 789,
    message: 'Title field is required'
  },
  data: {
  }
}

版本控制

由于API并非HTTP请求的唯一入口点，因此最好将API URI与其他URL区别开来。 我倾向于将前缀api放在所有URI上。

重要的是要了解，一旦发布了API并且其他人开始使用它，我们需要确保以后的更改不会破坏那些未相应更新其客户端的用户的使用。 因此，最好在所有API URI的前面加上版本号。 第一个可以称为v1，第二个可以称为v2，依此类推。 这样，我们将有自由实施可能会导致不兼容的更改作为单独的URI。

考虑到这两点，我们上一个关于book的示例将类似于以下内容： / api / v1 / books

例子

最后，让我们来看一些有关书籍的例子。

索取书籍清单

通讯协定：GET
URI：/ api / v1 / books
要求正文：EMPTY 响应：

{
  meta: {
  },
  data: [{
    id: 24,
    title: 'Behavior-Driven Development',
    author: 'Viktor Farcic'
  }, {
    id: 25,
    title: 'Continuous Integration',
    author: 'Viktor Farcic'
  }]
}

说明：请求从服务器检索所有书籍。

索取一本书

通讯协定：GET
URI：/ api / v1 / books / id / 24
要求正文：EMPTY 响应：

{
  meta: {
  },
  data: {
    id: 24,
    title: 'Behavior-Driven Development',
    author: 'Viktor Farcic'
  }
}

说明：请求从服务器中检索ID为24的书。

要求创建书籍

通讯协定：POST
URI：/ api / v1 / books
要求正文：

{
  id: 24,
  title: 'Behavior-Driven Development',
  author: 'Viktor Farcic'
}

状态为201的响应：

{
  meta: {
  },
  data: {
    uri: /api/v1/books/id/24
  }
}

说明：请求创建书籍。 服务器响应是201（已创建），带有URI，客户端可以使用它来检索所请求的书。

要求创建或修改书籍

协议：PUT
URI：/ api / v1 / books
要求正文：

{
  id: 24,
  author: 'Viktor Farcic'
}

状态为412的响应：

{
  meta: {
    error: 789,
    message: 'Title field is required'
  },
  data: {
  }
}

说明：请求修改或创建书籍。 服务器响应为412（前提条件失败），其中包含错误代码和描述问题的消息。

要求移除书籍

通讯协定：DELETE
URI：/ api / v1 / books
要求正文：

{
  id: 24
}

状态为202的响应：

{
  meta: {
  },
  data: {
  }
}

说明：要求删除该书。 服务器响应为202（已接受），表示服务器已接受请求，但处理尚未完成。 换句话说，服务器立即做出了响应，并且删除正在进行中。

翻译自: https://www.javacodegeeks.com/2014/08/rest-api-with-json.html