文章目录
REST简介
REST风格的架构
使用“api”作为上下文
增加一个版本标识
标识资源
确定HTTP Method
确定HTTP Status

REST简介
REST，即Representational State Transfer的缩写，翻译为“表现层状态转化”，如果一个架构符合REST原则，则称其为RESTful架构。

资源（Resources）

REST的名称“表现层状态转化”，表现层指的是“资源”的“表现层”。

所谓“资源”，就是网络上的一个实体，或者说是网络上的一个具体信息，它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实体。可以用一个具体的URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以。

因此URL就成了每个资源的地址或第一无二的标识符。

表现层

“资源”是一种信息实体，可以有多种外在表现形式。将“资源”具体呈现出来的形式称之为“表现层”。比如，文本可以用txt格式表现，也可用HTML格式、XML格式、JSON格式等。
URI只代表资源的实体，不代表它的形式。它的具体表现形式应该在HTTP请求的头信息中用Accept和Content-Type字段指定。

状态转化

访问一个网站。就代表了客户端和服务器的一个互动过程，这个过程中，势必涉及和状态的变化。

HTTP协议是一个无状态互联网通信协议，这意味着所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生“状态转化”。而这种转化是建立在表现层之上的，所以就是“表现层状态转化”。
URI：统一资源标识符
URL：统一资源定位符

REST风格的架构
包括了REST架构中如何标识资源，如何标识操作接口以及操作的版本，如何标识操作的结果等，如：

使用“api”作为web上下文；
增加版本标识；
标识资源；
REST中的HTTP Method；
REST中的HTTP Status；

使用“api”作为上下文
建议使用“api”作为上下文，如：
http://localhost/api
http://api.xxx.com

增加一个版本标识
http://localhost/api/v1.1

标识资源
将资源名称放到URL中，如果资源有层级关系，则放入层级关系：
http://localhost:/api/v1.1/user
//如果用户属于系统管理，则：
http://localhost:/api/v1.1/system/user

确定HTTP Method
在REST中，HTTP Method通常对应以下含义：

POST：代表增加资源；
PUT：代表更改资源，客户端提供完整的资源属性；
GET：代表查询资源；
PATCH：更新资源，客户端提供仅需要更改的资源属性；
DELETE：删除资源；
OPTIONS：用于获取URI所支持的方法，响应信息会在HTTP头中包含一个名为“Alllow”的头，值是所支持的方法，如“GET”、“POST”。


在业务系统中，删除往往不是指物理删除，而是逻辑删除，资源通常仍在数据库中，只是状态设置为删除状态。

确定HTTP Status
服务器向客户端返回HTTP Status以表示操作是否成功，常用的如下：

200，OK，用户请求成功，如查询数据成功返回。
400，错误的请求，如URI匹配上的Controller，但是方法参数匹配错误，就会抛出错误。
404NOT Found，用户发出的请求针对的资源不存在。通常是Controller没有匹配上URI，或者匹配上了Controller方法，但渲染的视图不存在。
405，用来访问本页面的HTTP Method不被允许，比如通过HTTP GET方式访问了一个@PostMapping的Controller方法。
406，表示无法使用请求的内容来响应请求的资源，如请求后缀以html结尾，但同时请求的HTTP头中又包含了Accept:application/json。
500，服务器内部错误，无法完成请求，通常是Controller抛出的错误。

REST由Roy Fielding于2000年在他的博士论文中引入和定义。REST是用于设计分布式系统的架构风格。它不是标准，而是一组约束，例如无状态，具有客户端/服务器关系和统一接口。REST与HTTP并不严格相关，但最常与它相关联。

REST原理


Resources 公开易于理解的目录结构URI。
Representations 传输JSON或XML以表示数据对象和属性。
Messages 显式使用HTTP方法（例如，GET，POST，PUT和DELETE）。
Stateless 交互在请求之间不在服务器上存储客户端上下文。状态依赖性限制并限制可伸缩性。客户端保持会话状态。


HTTP方法

使用HTTP方法将CRUD（创建，检索，更新，删除）操作映射到HTTP请求。

GET

检索信息。GET请求必须是安全且幂等的，这意味着无论使用相同参数重复多少次，结果都是相同的。它们可能有副作用，但用户并不期望它们，因此它们对系统的操作不是至关重要的。请求也可以是部分或有条件的。
检索ID为1的地址：
GET /addresses/1


POST

请求URI上的资源对提供的实体执行某些操作。POST通常用于创建新实体，但也可用于更新实体。
创建一个新地址：
POST /addresses


PUT

将实体存储在URI中。PUT可以创建新实体或更新现有实体。PUT请求是幂等的。幂等性是PUT与POST请求的期望之间的主要区别。
修改ID为1的地址：
PUT /addresses/1

注意: PUT替换现有实体。如果仅提供数据元素的子集，则其余的将替换为空或null。

PATCH

仅更新URI上实体的指定字段。PATCH请求既不安全也不是幂等（RFC 5789）。这是因为PATCH操作无法确保整个资源已更新。
PATCH /addresses/1


DELETE

请求删除资源; 但是，不必立即删除资源。它可能是异步或长时间运行的请求。
删除ID为1的地址：
DELETE /addresses/1


HTTP状态代码

状态代码表示HTTP请求的结果。

1XX - 信息
2XX–成功
3XX - 重定向
4XX - 客户端错误
5XX - 服务器错误


媒体类型

Accept和Content-Type HTTP头可以用来描述在HTTP请求中发送或请求的内容。如果客户端请求json格式的响应，则可以将Accept设置为application/json。相反，在发送数据时，将内容类型设置为application/xml会告诉客户机请求中发送的数据是xml。

文章目录
1.背景
1.传统下的API接口
对比
规则
概念
REST 系统的特征
演化
优点&缺点
是什么？

1.背景

1.传统下的API接口
http是目前在互联网上使用最多的协议，没有之一。

　　可是http的创始人一直都觉得，在过去10几年来，所有的人都在错误的使用Http.这句话怎么说呢？

　　如果说你要删除一个数据，以往的做法通常是 delete/{id}　

　　如果你要更新一个数据，可能是Post数据放Body，然后方法是 update/{id}， 或者是artichle/{id}?method=update　

　　 这种做法让Roy Fielding很暴燥，他觉得这个世界不该这样的，所有的人都在误解而且在严重错误的误解Http的设计初衷，好比是发明了火药却只用它来做烟花爆竹。

　　 那么正确的使用方式是什么呢？如果你要看Rest各种特性，你恐怕真的很难理解Rest，但是如果你看错误的使用http的人倒底儿了哪些错，什么是Rest就特别容易理解了。　

　　

七宗罪的第一条，混乱。
一万个人心里有一万个Url的命名规则，Url是统一资源定位符，重点是资源。而很多人却把它当成了万金油，每一个独立的虚拟的网页都可以随意使用，各种操作都能够迭加。这是混乱的来源之一。

比如：
https://localhost:8080/myweb/getUserById?id=1
https://localhost:8080/myweb/user/getById?id=1
https://localhost:8080/myweb/x/y?id=1

第二条，贪婪。
有状态和无状态全部混在一起。特别是在购物车或者是登录的应用中，经常刷新就丢失带来的用户体验简直棒棒哒。每一个请求并不能单独的响应一些功能，很多的功能混杂在一起里。这是人性贪婪的本质，也是各种Hack的起源，只要能够把问题解决掉，总会有人用他认为最方便的方式去解决问题，比如说汽车门把手坏掉了直接系根绳子当把手，emmmm这样确实很棒啊。

　　

第三条，无序。
返回的结果往往是很随意，各种错误信息本来就是用Http的状态码构成的，可是很多人还是喜欢把错误信息返回在返回值中。最常见的就是Code和Message，当然对于这一点，我个人是保留疑问的，我的观点是，Http本身的错误和服务器的内部错误还是需要在不断层面分开的，不能混在一起。可是在大神眼里并非如此。
那么怎么解决这些问题呢？
强迫症患者的福音就是先颁规则，第一个规则就是明确Url是什么，该怎么用。就是所有的Url本质来讲，都应该是一种资源。一个独立的Url地址，就是对应一个独一无二的资源。怎么样？这种感觉是不是棒棒哒？一个冰淇淋，一个老师，一间房子，在Url上对应的都是一个资源，不会有多余的Url跟他对应，也不会表示有多个Url地址　

　　注意，这里点的是Url地址，并不是单独的参数，他就是一个/room/{room_id}这样的东西，举个栗子,/room/3242 这就表示3242号房间。这是一个清爽的世界啊，你想想，之前的Url是什么都要，我开房，可能是/open/room/3242 我要退房可能是/exit/3242/room，我要打理房间，可能是room/3242?method=clean.够了！这些乱七八糟的东西全够了，让世界回归清爽的本质，一间房，就是/room/3242 没有别的Url地址了。

　　在过去的混乱世界里，经常用的就是Get和Post。如果不是因为Get不支持大数据传输，我想连Post都不会有人使用。（想像一下Roy Fielding在愤怒的对着电脑屏幕喊，Http的Method一共有八个，你们为毛只逮着Get一只羊的毛薅薅薅薅薅）。
而对资源最常见的操作是什么？CRUD，对不对，就是创建，读，更新，删除。再看Http的Method？是不是非常完美？其实也怪Fielding老爷子一开始命名不准确，如果刚开始就是把Get方法叫做Read，Put方法叫做Update，Post叫做Create这该多好。。。

　　你用一个Get，大家又发现没什么限制没什么所谓，又很难理解Put和Post的差别，法无禁止即可为啊，呃，老爷子不要瞪我，我瞎说的。总之，这四种方法够不够你浪？你有本身找出来更多的对资源的操作来啊，我还有4个Method没用过呢。如果这4个真的不够了，有什么问题，大不了我再重新更改http协议啊。其实简单说，对于Rest理解到这里就够了。后续的东西，都是在这一条基础上空想出来的，比强迫症更强迫症，当然，无状态我是百分百支持的。以上的各种表述可能不太准确，也纯属是我的意淫和各种小道资料，并未考据，但是凭良心讲，我是早就看不惯黑暗年代里的Url命名风格了，所以当时最早接触到Rest的时候，瞬间就找到了真爱，我靠，这不就是我一直想要的答案吗？但是我一直想的仅仅是命名规范，从来没有把自己的思考角度放在一个url就是一个资源，所有的操作都是对资源的更改而言的角度上啊。所以你能理解到的程度，更多的就是在于你要弄清楚你要解决的什么问题，如果你的问题只是理解Rest，恐怕你很理解，如果你的问题是怎么解决Url混乱的问题，你反而很快能弄懂了~
对比
https://localhost:8080/myweb/getDogs --> GET /rest/api/dogs 获取所有小狗狗 
https://localhost:8080/myweb/addDogs --> POST /rest/api/dogs 添加一个小狗狗 
https://localhost:8080/myweb/updateDogs/:dog_id --> PUT /rest/api/dogs/:dog_id 修改一个小狗狗 
https://localhost:8080/myweb/deleteDogs/:dog_id --> DELETE /rest/api/dogs/:dog_id 删除一个小狗狗

左边是我们写的，而且后台我们可能会写出很多返回值，而且各种各样的，比如

https://localhost:8080/myweb/addDogs
操作成功 或者 1

或者
操作失败 或者 0

这还要我们自己去解析，还要前端和后端去协商你返回的0是啥意识啊。但是REST返回值是标准的，比如
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
 
{
   "url" : "/api/categories/1",
   "label" : "Food",
   "items_url" : "/api/items?category=1",
   "brands" : [
         {
            "label" : "友臣",
            "brand_key" : "32073",
            "url" : "/api/brands/32073"
         }, {
            "label" : "乐事",
            "brand_key" : "56632",
            "url" : "/api/brands/56632"
         }
         ...
   ]
}

格式固定，第一行永远是操作失败或者成功的状态码，第二行是返回的类型，第三行内容的长度，第五行开始是内容。
这样我只需写一个程序解析返回的信息就可以了，可以重用，但是我们上面传统的不仅仅要协商，还有有不同的解析程序，稍微改变，就不能正常使用了。所以rest的明显更加通用。
列子2
1、获取文章

请求：
GET /blog/post/{postId} HTTP/1.1

响应：
HTTP/1.1 200 OK
{
    "title": "foobar",
    "content": "foobar",
    "comments": ["", "", ""]
}

2、发布文章

请求：
POST /blog/post HTTP/1.1
{
    "title": "foobar",
    "content": "foobar",
    "comments": ["", "", ""]
}

响应：
HTTP/1.1 201 CREATED

规则
GET    用来获取资源，
POST  用来新建资源（也可以用于更新资源），
PUT    用来更新资源，
DELETE  用来删除资源

例子
DELETE http://api.qc.com/v1/friends: 删除某人的好友 （在http parameter指定好友id）
POST http://api.qc.com/v1/friends: 添加好友UPDATE 
http://api.qc.com/v1/profile: 更新个人资料


概念
REST 是面向资源的，这个概念非常重要，而资源是通过 URI 进行暴露。

URI 的设计只要负责把资源通过合理方式暴露出来就可以了。对资源的操作与它无关，操作是通过 HTTP动词来体现，所以REST 通过 URI 暴露资源时，会强调不要在 URI 中出现动词。
比如：左边是错误的设计，而右边是正确的
GET /rest/api/getDogs --> GET /rest/api/dogs 获取所有小狗狗 
GET /rest/api/addDogs --> POST /rest/api/dogs 添加一个小狗狗 
GET /rest/api/editDogs/:dog_id --> PUT /rest/api/dogs/:dog_id 修改一个小狗狗 
GET /rest/api/deleteDogs/:dog_id --> DELETE /rest/api/dogs/:dog_id 删除一个小狗狗

REST很好地利用了HTTP本身就有的一些特征，如HTTP动词、HTTP状态码、HTTP报头等等

REST API 是基于 HTTP的，所以你的API应该去使用 HTTP的一些标准。这样所有的HTTP客户端（如浏览器）才能够直接理解你的API（当然还有其他好处，如利于缓存等等）。REST 实际上也非常强调应该利用好 HTTP本来就有的特征，而不是只把 HTTP当成一个传输层这么简单了。
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx

{
   "url" : "/api/categories/1",
   "label" : "Food",
   "items_url" : "/api/items?category=1",
   "brands" : [
         {
            "label" : "友臣",
            "brand_key" : "32073",
            "url" : "/api/brands/32073"
         }, {
            "label" : "乐事",
            "brand_key" : "56632",
            "url" : "/api/brands/56632"
         }
         ...
   ]
}

看这个响应，包含了http里面的状态码等信息。还会有http的一些报头。
Authorization 认证报头 
Cache-Control 缓存报头 
Cnotent-Type  消息体类型报头 
......

REST 系统的特征

客户-服务器（Client-Server），提供服务的服务器和使用服务的客户需要被隔离对待。
无状态（Stateless），来自客户的每一个请求必须包含服务器处理该请求所需的所有信息。换句话说，服务器端不能存储来自某个客户的某个请求中的信息，并在该客户的其他请求中使用。
可缓存（Cachable），服务器必须让客户知道请求是否可以被缓存。（Ross：更详细解释请参考 理解本真的REST架构风格 以及 StackOverflow 的这个问题 中对缓存的解释。）
分层系统（Layered System），服务器和客户之间的通信必须被这样标准化：允许服务器和客户之间的中间层（Ross：代理，网关等）可以代替服务器对客户的请求进行回应，而且这些对客户来说不需要特别支持。
统一接口（Uniform Interface），客户和服务器之间通信的方法必须是统一化的。（Ross：GET,POST,PUT.DELETE, etc）
支持按需代码（Code-On-Demand，可选），服务器可以提供一些代码或者脚本（Ross：Javascrpt，flash，etc）并在客户的运行环境中执行。这条准则是这些准则中唯一不必必须满足的一条。（Ross：比如客户可以在客户端下载脚本生成密码访问服务器。）

详细解释
无状态（Stateless）
所谓无状态的，即所有的资源，都可以通过URI定位，而且这个定位与其他资源无关，也不会因为其他资源的变化而改变。有状态和无状态的区别，举个简单的例子说明一下。如查询员工的工资，如果查询工资是需要登录系统，进入查询工资的页面，执行相关操作后，获取工资的多少，则这种情况是有状态的，因为查询工资的每一步操作都依赖于前一步操作，只要前置操作不成功，后续操作就无法执行；如果输入一个url即可得到指定员工的工资，则这种情况是无状态的，因为获取工资不依赖于其他资源或状态，且这种情况下，员工工资是一个资源，由一个url与之对应，可以通过HTTP中的GET方法得到资源，这是典型的RESTful风格。


统一接口（Uniform Interface）
RESTful架构风格规定，数据的元操作，即CRUD(create, read, update和delete,即数据的增删查改)操作，分别对应于HTTP方法：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源，这样就统一了数据操作的接口，仅通过HTTP方法，就可以完成对数据的所有增删查改工作。
即：
GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）。
PATCH（UPDATE）：在服务器更新资源（客户端提供需要修改的资源数据）。
DELETE（DELETE）：从服务器删除资源。

演化
https://zhuanlan.zhihu.com/p/30396391?group_id=937244108725641216
优点&缺点
优点是因为他对uri进行了限制，只用于定义资源。这样看起来比较容易理解。尤其是对简单的对象的增删改查，很好理解。
缺点是因为这种限制，导致设计uri变得复杂了。尤其是复杂的关系，操作，资源集合，硬性套用rest原则设计非常困难。在rest基础上的HATEOAS，返回的json里增加了相应的关系和url。这也同样带来问题。好处是对简单的关系，的确可以通过url进一步处理。但对复杂的关系和操作，HATEOAS并不能胜任描述。反而在单纯的数据中增加了一堆垃圾信息。
是什么？
REST是一个标准，一种规范，遵循REST风格可以使开发的接口通用，便于调用者理解接口的作用。
参考：

https://www.zhihu.com/question/28557115

https://blog.igevin.info/posts/restful-architecture-in-general/

RestHttp

项目地址：RestHttp

简介：Android 基于 HttpURLConnection 简单易用的网络库，支持 Http，Https，Http 文件上传，图片加载，面向接口的 API 调用方式，轻量的设计风格，Android 初学者的学习教程


RestHttp 提供了三级缓存（服务器缓存，内存缓存，硬盘缓存），通过动态代理的方式实现了面向接口调用 API。
封装了 HttpURLConnection，简单易用的 API 设计。
Debug 模式下设置日志 TAG，所有网络请求日志输出，方便调试。
gradle 依赖
compile 'cn.alien95:resthttp:1.0.5'

使用方法
初始化：设置日志 TAG
public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        RestHttp.initialize(this);
        Utils.initialize(this);
        RestHttp.setDiskCacheSize(100 * 1024 * 1024);
        if (BuildConfig.DEBUG) {
            Utils.setDebug(true,"Debug");
            RestHttp.setDebug(true, "network");
        }
    }
}


通过接口定义 API
API 接口类
public interface ServiceAPI {

    //同步请求方式：不能包含 Callback 参数
    @POST("/v1/users/login.php")
    UserInfo loginPostSync(@Field("name")
                   String name,
                   @Field("password")
                   String password);

    //异步请求：必须有一个 Callback 参数作为回调
    @POST("/v1/users/login.php")
    void loginAsyn(@Field("name")
                String name,
                   @Field("password")
                String password, RestCallback<UserInfo> restCallback);

    //GET 请求同步
    @GET("/v1/users/login_get.php")
    UserInfo loginGetSync(@Query("name")
                          String name,
                          @Query("password")
                          String password);

    //GET 请求异步
    @GET("/213-4")
    void getMusicData(@Query("topid") int topId,
                      @Query("showapi_appid") String showapiAppId,
                      @Query("showapi_sign") String secretKey,
                      RestCallback<String> callback);
}


Java 类方式请求数据
Http --- GET,POST
    public void get(){
        mResult.setText("");
        HttpRequest.getInstance().get(GET_URL, new HttpCallback() {
            @Override
            public void success(String info) {
                mResult.setText(new Gson().toJson(info));
            }
        });
    }

    public void post(){
        mResult.setText("");
        Map<String,String> params = new HashMap<>();
        params.put("page","1");
        HttpRequest.getInstance().addHeader("UID","1");
        HttpRequest.getInstance().addHeader("token","9ba712a6210728364ea7c2d7457cde");
        HttpRequest.getInstance().post(POST_URL, params,new HttpCallback() {
            @Override
            public void success(String info) {
                mResult.setText(new Gson().toJson(info));
            }
        });
    }


Http 文件上传
HttpFile.getInstance().uploadFile(UPLOAD_URL, null, "picture", mImageFile, new HttpCallback() {
   @Override
   public void success(String info) {
       Utils.Toast(info + " : http://115.29.107.20/image/test_upload.jpg");
   }
}


Https
HttpsRequest.getInstance().get("https://baidu.com/", new HttpsCallback() {
   @Override
   public void success(String info) {
        mResult.setText(info);
   }
});


图片加载 --- 支持大图压缩
HttpImageView
 <cn.alien95.resthttp.view.HttpImageView
     android:id="@+id/image"
     android:layout_width="match_parent"
     android:layout_height="wrap_content"
     android:layout_marginTop="16dp"
     android:adjustViewBounds="true" />

 imageView.setImageUrl(imageUrl);

可以指定压缩比例或固定的宽和高
image.setInSimpleSize(inSimpleSize);
image.setImageUrlWithCompress(IMAGE_SMALL_URL, 800, 600);


注意事项
依赖的其他库
    compile 'com.jakewharton:disklrucache:2.0.2'
    compile 'com.google.code.gson:gson:2.6.2'


详细用法请看 Demo