Restful Web Guide

资源:REST 架构把所有内容都视为资源。

消息

    请求

        动作（Verb） - 表明 HTTP 方法，比如 GET，POST，DELETE，PUT 等等。

        URI - 用来标识服务器上资源的统一资源标示符（URI）。

        HTTP 版本 - 表明 HTTP 版本，比如 HTTP v1.1。

        请求头 - 包含 HTTP 请求消息的元数据，它是键-值对形式的。比如，客户端（或者浏览器）类型，客户端支持的格式，消息体格式，缓存设置等等。

        请求体 - 消息内容或者资源表示形式。

    响应

        状态/响应码 - 表明请求资源的服务器状态。比如 404 意味着资源没有找到或者 200 意味着响应 OK。

        HTTP 版本 - 表明 HTTP 版本，比如 HTTP v1.1。

        响应头 - 包含 HTTP 响应消息的元素数据，它是键-值对形式的。比如，内容长度，内容类型，响应日期，服务器类型等等。

        响应体 - 响应消息内容或者资源表示形式。

标准URI

    规范

        localhost:8080/项目名称/项目服务总体前缀/处理student对象的签注/最后前缀

        localhost:8080/Student/studentinfo/student/getStudentInfo

    注意点:

        使用复数名词 - 使用复数名词定义资源。比如，我们使用 users 标识用户资源。

        避免使用空格 - 处理长资源名时使用下划线（_）或者连字符（-），比如，用 authorized_users 而不是 authorized%20users。

        使用小写字母 - 尽管 URI 不区分带小写，但是在 url 中使用小写字母是一种很好的做法。

        保持向后兼容 - 由于 Web 服务是一种公共服务，URI 一旦公开之后应该始终可用。这种情况下，要更新 URI，请使用 HTTP 状态码 - 300 重定向老的 URI 到新的 URI。

        使用 HTTP Verb - 始终使用 HTTP Verb，比如 GET，PUT 以及 DELETE 处理资源操作。在 URL 中使用操作名并不好。

方法/动作

    GET        只读    获取用户列表 

    GET         只读    获取 ID 为 1 的用户 

    PUT         幂等    插入 ID 为 1 的用户 

    POST        N/A     更新 ID 为 1 的用户 

    DELETE      幂等    删除 ID 为 1 的用户 

    OPTIONS     只读    列出 Web 服务所支持的操作 

    HEAD        只读    只返回 HTTP 头，不返回 HTTP 体 

    *幂等的意味着它们的结果总是相同的，无论这个操作被调用多少次。

特点:

    无状态：

        一个 RESTful Web 服务不应该在服务器上保持客户端状态。这种约束被称为无状态。

        优点:

            Web 服务可以独立对待每个请求方法。

            Web 服务不需要维护客户端先前的交互。简化了应用程序设计。

            HTTP 本身是一个无状态协议，RESTful Web 服务可与 HTTP 协议无缝协作。

        缺点:

            Web 服务需要在每个请求中获取额外的信息，然后在客户端交互需要处理的情况下解读客户端状态

    缓存:缓存是指在客户端存储服务器响应，以便客户端不需要一次又一次的请求服务器上相同的资源。服务器响应应该有关于如何进行缓存的信息，以便客户端缓存一段时间内的响应或者永远不缓存服务器响应。

        Date:创建资源的日期和时间。

        Last Modified:最后修改资源的日期和时间。

        Cache-Control:控制缓存的主要头信息。

            Public:表明该资源可由任何组件缓存。

            Private:表明该资源只能由客户端和服务器缓存，没有中介可以缓存该资源。

            no-cache/no-store:表明该资源不可缓存。

            max-age:表明缓存在 max-age 指定的秒数内有效。之后，客户端就必须发起另一个请求。

            must-revalidate:表明如果 max-age 已经过去了服务器要重新验证资源。

        Expires:缓存到期的日期和时间。

        Age:从服务器获取资源持续的秒数。

    安全性:

        验证 - 验证服务器上的所有输入。保护服务器免受 SQL 或者 NoSQL 注入攻击。

        基于会话的认证 - 请求一个 Web 服务方法时使用基于会话的认证对用户进行身份验证。

        URL 不要有敏感数据 - 永远不要在 URL 中使用用户名，密码或者会话标记，这些值应该通过 POST 方法传递给 Web 服务。

        限制方法执行 - 允许限制使用方法，比如 GET，POST，DELET。GET 方法不应该能够删除数据。

        验证有缺陷的 XML/JSON - 检查格式良好的输入传递给 Web 服务方法。

        抛出通用错误消息 - Web 服务方法应该使用 HTTP 错误消息，比如 403 展示禁止访问等。

常用HTTP状态码:

    200 OK ，显示成功。

    201 CREATED ，当资源使用 POST 或者 PUT 请求建立成功时。使用位置头返回新建资源的链接。

    204 NO CONTENT ，当响应体为空时。比如，DELETE 请求。

    304 NOT MODIFIED 在有条件的 GET 请求的情况下用于减少网络带宽的使用。响应体应该为空。头信息应该包含日期，位置等。

    400 BAD REQUEST ，指出提供的输入无效。比如验证错误，数据缺失。

    401 UNAUTHORIZED ，指出用户正在使用无效的或者错误的认证令牌。

    403 FORBIDDEN ，指出用户没有使用访问方法。比如，没有管理员权限访问删除操作。

    404 NOT FOUND ，指出该方法不可用。

    409 CONFLICT ，指出执行方法时冲突，比如添加重复的条目。

    500 INTERNAL SERVER ERROR ，指出执行该方法时服务器抛出了一些异常。

JAX-RS常用注解

    @Path 资源类或方法的相对路径。

    @GET HTTP Get 请求，用来提取资源。

    @PUT HTTP PUT 请求，用来创建资源。

    @POST HTTP POST 请求，用来创建或更新资源。

    @DELETE HTTP DELETE 请求，用来删除资源。

    @HEAD HTTP HEAD 请求，用来获取方法可用的状态。

    @Produces 由 Web 服务生成的 HTTP 响应，比如 APPLICATION/XML，TEXT/HTML，APPLICATION/JSON 等。

    @Consumes HTTP 请求类型，比如 application/x-www-form-urlencoded 在 POST 请求期间在 HTTP 体中接受表单数据。

    @PathParam 绑定传递给方法的参数为路径中的某个值。

    @QueryParam 绑定传递给方法参数为路径中的某个查询参数。

    @MatrixParam 绑定传递给方法参数为路径中的某个 HTTP 矩阵参数。

    @HeaderParam 绑定传递给方法的参数为 HTTP 头。

    @CookieParam 绑定传递给方法的参数为某个 Cookie。

    @FormParam 绑定传递给方法的参数为某个表单值。

    @DefaultValue 给传递给方法的参数分配一个默认值。

    @Context 资源上下文，比如将 HTTP 请求作为上下文。