restful接口开发实例,如何设计好的RESTful API
restful接口开发实例,如何设计好的RESTful API详细介绍
本文目录一览： flask编写RESTful API
REST(Representational State Transfer)是一种架构风格，表述了网络中客户端于服务端的一种交互，REST本身是不实用的，关键的是如何设计它。REST架构就是为了HTTP协议设计的。RESTful web services的核心概念是管理资源。资源是由URIs来表示，客户端使用HTTP当中的'POST,GET, PUT, DELETE'等方法发送请求到服务器，改变相应的资源状态。
Flask是一个基于Python开发的微型web框架，其中Werkzeug本质是Socket服务端，其用于接收http请求并对请求进行预处理，然后触发Flask框架，开发人员基于Flask框架提供的功能对请求进行相应的处理，并返回给用户。
一个简单的例子：
这里又两种方法构造服务，第一中就是利用flask的路由进行构造，另外一种就是利用flask 的扩展插件来构造。首先我们假定一种业务场景： 做一个最简单的图书馆里系统，实现如下功能
了解过HTTP的都了解这该如何做，那么使用flask 会怎么构造服务呢？又两种办法 1. 利用路由写。2.利用flask的扩展插件写 接卸来就开始介绍这两种方法如何实现吧！
在实现之前可以使用postman 对接口进行测试
未完待续
如何使用RestTemplate访问restful服务
定义一个简单的restful接口
@RestController
public class TestController
{
@RequestMapping(value = "testPost", method = RequestMethod.POST)
public ResponseBean testPost(@RequestBody RequestBean requestBean)
{
ResponseBean responseBean = new ResponseBean();
responseBean.setRetCode("0000");
responseBean.setRetMsg("succ");
return responseBean;
}
}
使用RestTemplate访问该服务
//请求地址
String url = "http://localhost:8080/testPost";
//入参
RequestBean requestBean = new RequestBean();
requestBean.setTest1("1");
requestBean.setTest2("2");
requestBean.setTest3("3");
RestTemplate restTemplate = new RestTemplate();
ResponseBean responseBean = restTemplate.postForObject(url, requestBean, ResponseBean.class);
从这个例子可以看出，使用restTemplate访问restful接口非常的简单粗暴无脑。(url,
requestMap, ResponseBean.class)这三个参数分别代表 请求地址、请求参数、HTTP响应转换被转换成的对象类型。
RestTemplate方法的名称遵循命名约定，第一部分指出正在调用什么HTTP方法，第二部分指示返回的内容。本例中调用了restTemplate.postForObject方法，post指调用了HTTP的post方法，Object指将HTTP响应转换为您选择的对象类型。还有其他很多类似的方法，有兴趣的同学可以参考官方api。
三.手动指定转换器(HttpMessageConverter)
我们知道，调用reseful接口传递的数据内容是json格式的字符串，返回的响应也是json格式的字符串。然而restTemplate.postForObject方法的请求参数RequestBean和返回参数ResponseBean却都是java类。是RestTemplate通过HttpMessageConverter自动帮我们做了转换的操作。
默认情况下RestTemplate自动帮我们注册了一组HttpMessageConverter用来处理一些不同的contentType的请求。
如StringHttpMessageConverter来处理text/plain;MappingJackson2HttpMessageConverter来处理application/json;MappingJackson2XmlHttpMessageConverter来处理application/xml。
你可以在org.springframework.http.converter包下找到所有spring帮我们实现好的转换器。
如果现有的转换器不能满足你的需求，你还可以实现org.springframework.http.converter.HttpMessageConverter接口自己写一个。详情参考官方api。
选好了HttpMessageConverter后怎么把它注册到我们的RestTemplate中呢。
RestTemplate restTemplate = new RestTemplate();
//获取RestTemplate默认配置好的所有转换器
List
<httpmessageconverter
> messageConverters = restTemplate.getMessageConverters();
//默认的MappingJackson2HttpMessageConverter在第7个 先把它移除掉
messageConverters.remove(6);
//添加上GSON的转换器
messageConverters.add(6, new GsonHttpMessageConverter());
这个简单的例子展示了如何使用GsonHttpMessageConverter替换掉默认用来处理application/json的MappingJackson2HttpMessageConverter。
四.设置底层连接方式
要创建一个RestTemplate的实例，您可以像上述例子中简单地调用默认的无参数构造函数。这将使用java.NET包中的标准Java类作为底层实现来创建HTTP请求。
但很多时候我们需要像传统的HttpClient那样设置HTTP请求的一些属性。RestTemplate使用了一种很偷懒的方式实现了这个需求，那就是直接使用一个HttpClient作为底层实现......
//生成一个设置了连接超时时间、请求超时时间、异常最大重试次数的httpClient
RequestConfig config = RequestConfig.custom().setConnectionRequestTimeout(10000).setConnectTimeout(10000).setSocketTimeout(30000).build();
HttpClientBuilder builder = HttpClientBuilder.create().setDefaultRequestConfig(config).setRetryHandler(new DefaultHttpRequestRetryHandler(5, false));
HttpClient httpClient = builder.build();
//使用httpClient创建一个ClientHttpRequestFactory的实现
ClientHttpRequestFactory requestFactory = new HttpComponentsClientHttpRequestFactory(httpClient);
//ClientHttpRequestFactory作为参数构造一个使用作为底层的RestTemplate
RestTemplate restTemplate = new RestTemplate(requestFactory);
五.设置拦截器(ClientHttpRequestInterceptor)
有时候我们需要对请求做一些通用的拦截设置，这就可以使用拦截器进行处理。拦截器需要我们实现org.springframework.http.client.ClientHttpRequestInterceptor接口自己写。
举个简单的例子，写一个在header中根据请求内容和地址添加令牌的拦截器。
public class TokenInterceptor implements ClientHttpRequestInterceptor
{
@Override
public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException
{
//请求地址
String checkTokenUrl = request.getURI().getPath();
//token有效时间
int ttTime = (int) (System.currentTimeMillis() / 1000 + 1800);
//请求方法名 POST、GET等
String methodName = request.getMethod().name();
//请求内容
String requestBody = new String(body);
//生成令牌 此处调用一个自己写的方法，有兴趣的朋友可以自行google如何使用ak/sk生成token，此方法跟本教程无关，就不贴出来了
String token = TokenHelper.generateToken(checkTokenUrl, ttTime, methodName, requestBody);
//将令牌放入请求header中
request.getHeaders().add("X-Auth-Token",token);
return execution.execute(request, body);
}
}
创建RestTemplate实例的时候可以这样向其中添加拦截器
RestTemplate restTemplate = new RestTemplate();
//向restTemplate中添加自定义的拦截器
restTemplate.getInterceptors().add(new TokenInterceptor());
一. 什么是RestTemplate
传统情况下在Java代码里访问restful服务，一般使用Apache的HttpClient。不过此种方法使用起来太过繁琐。spring提供了一种简单便捷的模板类来进行操作，这就是RestTemplate。
二、举个例子。 //请求地址
String url = "http://localhost:8080/testPost";
//入参
RequestBean requestBean = new RequestBean();
requestBean.setTest1("1");
requestBean.setTest2("2");
requestBean.setTest3("3");
RestTemplate restTemplate = new RestTemplate();
ResponseBean responseBean = restTemplate.postForObject(url, requestBean, ResponseBean.class);
从这个例子可以看出，使用restTemplate访问restful接口非常的简单粗暴无脑。(url,
requestMap, ResponseBean.class)这三个参数分别代表 请求地址、请求参数、HTTP响应转换被转换成的对象类型。
RestTemplate方法的名称遵循命名约定，第一部分指出正在调用什么HTTP方法，第二部分指示返回的内容。本例中调用了restTemplate.postForObject方法，post指调用了HTTP的post方法，Object指将HTTP响应转换为您选择的对象类型。
三.手动指定转换器(HttpMessageConverter)
我们知道，调用reseful接口传递的数据内容是json格式的字符串，返回的响应也是json格式的字符串。然而restTemplate.postForObject方法的请求参数RequestBean和返回参数ResponseBean却都是java类。是RestTemplate通过HttpMessageConverter自动帮我们做了转换的操作。
默认情况下RestTemplate自动帮我们注册了一组HttpMessageConverter用来处理一些不同的contentType的请求。
如StringHttpMessageConverter来处理text/plain;MappingJackson2HttpMessageConverter来处理application/json;MappingJackson2XmlHttpMessageConverter来处理application/xml。
你可以在org.springframework.http.converter包下找到所有spring帮我们实现好的转换器。
如果现有的转换器不能满足你的需求，你还可以实现org.springframework.http.converter.HttpMessageConverter接口自己写一个。
四.设置底层连接方式
要创建一个RestTemplate的实例，您可以简单地调用默认的无参数构造函数。这将使用java.NET包中的标准Java类作为底层实现来创建HTTP请求。
但很多时候我们需要像传统的HttpClient那样设置HTTP请求的一些属性。RestTemplate使用了一种很偷懒的方式实现了这个需求，那就是直接使用一个HttpClient作为底层实现......
五.设置拦截器(ClientHttpRequestInterceptor)
有时候我们需要对请求做一些通用的拦截设置，这就可以使用拦截器进行处理。拦截器需要我们实现org.springframework.http.client.ClientHttpRequestInterceptor接口自己写。
以上是如何使用RestTemplate方便快捷的访问restful接口。其实RestTemplate的功能非常强大
</httpmessageconverter
如何设计好的RESTful API
安全是恒久的话题，对于基于WSDL和SOAP的Web Service，我们有WS-Security这样的安全规范来指导实现认证、授权、身份管理等安全需求。那么，RESTful API有无成熟可用规范或实现框架呢？如何保证RESTful API的安全性呢？
如何对RESTful API进行版本控制，请分享您认为实用的做法？
HTTP1.1规范中给出的动词对于设计RESTful API够用吗？您在实际项目中会扩展自己的动词吗？在什么情况下需要扩展？
今年5月份发布的JAX-RS 2.0规范对于RSTfulAPI的设计最有价值的特性是哪个（些）? 它（们）用于解决什么问题？
能否为InfoQ的读者们推荐一款实用的RESTful API开发框架，并说明您的推介理由。
HTTP2.0规范正在制定当中，您对它的期待是什么？
InfoQ：什么是好的RESTful API？相信每个人都有自己的评判标准。那么，您认为一个好的RESTful API应该具有哪些特征呢？
李锟：一个好的RESTful API，应该具备以下特征：
这个API应该是对浏览器友好的，能够很好地融入Web，而不是与Web格格不入。
浏览器是最常见和最通用的REST客户端。好的RESTful API应该能够使用浏览器+HTML完成所有的测试（不需要使用编程语言）。这样的API还可以很方便地使用各种自动化的Web功能测试、性能测试工具来做测试。Web前端应用（基于浏览器的RIA应用、移动App等等）也可以很方便地将多个RESTful API的功能组合起来，建造Mashup类的应用。
这个API中所包含的资源和对于资源的操作，应该是直观和容易理解的，并且符合HTTP协议的要求。
REST开发又被称作“面向资源的开发”，这说明对于资源的抽象，是设计RESTful API的核心内容。RESTful API建模的过程与面向对象建模类似，是以名词为核心的。这些名词就是资源，任何可命名的抽象概念都可以定义为一个资源。而HTTP协议并不是一种传输协议，它实际提供了一个操作资源的统一接口。对于资源的任何操作，都应该映射到HTTP的几个有限的方法（常用的有GET/POST/PUT/DELETE四个方法，还有不常用的PATCH/HEAD/OPTIONS方法）上面。所以RESTful API建模的过程，可以看作是具有统一接口约束的面向对象建模过程。
按照HTTP协议的规定，GET方法是安全且幂等的，POST方法是既不安全也不幂等的（可以用来作为所有写操作的通配方法），PUT、DELETE方法都是不安全但幂等的。将对资源的操作合理映射到这四个方法上面，既不过度使用某个方法（例如过度使用GET方法或POST方法），也不添加过多的操作以至于HTTP的四个方法不够用。
如果发现资源上的操作过多，以至于HTTP的方法不够用，应该考虑设计出更多的资源。设计出更多资源（以及相应的URI）对于RESTful API来说并没有什么害处。
这个API应该是松耦合的。
RESTful API的设计包括了三个循序渐进、由低到高的层次：资源抽象、统一接口、超文本驱动。正是这三个层次确保了RESTful API的松耦合性。
当设计面向互联网的API时，松耦合变成了一种“必须有”的强需求。紧耦合的API非常脆弱，一旦公布出去，服务器端和客户端都无法持续进化。尤其是服务器端，公布出去的接口根本不敢改，改了之后，几乎所有客户端应用立即无法正常工作。REST这种架构风格就是紧耦合API的解毒剂，这个话题可以谈的很深，这里就不展开了。感兴趣的读者可以参考《REST实战》。
这个API中所使用的表述格式应该是常见的通用格式
在RESTful API中，对于资源的操作，是通过在服务器端-客户端之间传递资源的表述来间接完成的。资源的表述可以有很多种格式，并且在响应和请求中的资源表述格式也会有所不同。GET/POST响应中的资源表述格式，常见的有HTML、XML、JSON；POST/PUT请求中的资源表述格式，常见的有标准的HTML表单参数、XML、JSON。
这些常见表述格式，处理起来非常容易，有大量的框架和库提供支持。所以除非有很合理的要求，通常不需要使用自定义的私有格式。
使用HTTP响应状态代码来表达各种出错情况
HTTP响应状态代码，是HTTP协议这个统一接口中用来表达出错情况的标准机制。响应状态代码分成两部分：status code和reason phase。两部分都是可定制的，也可以使用标准的status code，只定制reason phase。
如果一个所谓的“RESTful API”对于任何请求都返回200 OK响应，在响应的消息体中返回出错情况信息，这种做法显然不符合“确保操作语义的可见性”这个REST架构风格的基本要求。
这个API应该对于HTTP缓存是友好的
充分利用好HTTP缓存是RESTful API可伸缩性的根本。HTTP协议是一个分层的架构，从两端的user agent到origin server之间，可以插入很多中间组件。而在整个HTTP通信链条的很多位置，都可以设置缓存。HTTP协议内建有很好的缓存机制，可以分成过期模型和验证模型两套缓存机制。如果API设计者完全没有考虑过如何利用HTTP缓存，那么这个API的可伸缩性会有很多问题。
李建业：首先说明一下，对REST这个概念，我一般把它理解为REST风格的架构，但是现在实践中最为广泛认知的是HTTP，而它是REST的一个实现，所以RESTful API也可以不太严格的指基于HTTP的API——当然，即使是不严格的时候，API本身也应该力求遵循REST架构风格。
我认为，一个RESTful API最重要的一点应该是——“尽可能少的先验信息”，这一条也同时是我判断一个好的RESTful API的标准。
比如HTTP动词，在实践中，大家可能会常常纠结于有效利用 HTTP 动词，但这却并不是特别重要的事情——除非你理解这么做的价值。HTTP 动词最重要的地方在于它是标准阐明了的行为，也就是说，如果我们的“客户端”遵循约定，那么就不必要发明新的动词，也就不必增加“先验信息”；但是，所谓“先验信息”，针对的是客户端——对API来说就是调用者，对于一些企业内部系统，或者一些传统系统，由于“资源”很稳定，对资源的操作也很稳定，这些系统的“调用客户端”不是浏览器而是另一个系统，此时如果强制对应到HTTP动词，反而会变成额外的“先验信息”，这时我就不会太拘泥HTTP动词，自己制定一套动词放在参数中也可以接受——只要动词不变化，这个系统依然是REST风格的。
再比如Response里面的Content-Type，这个有时会被新手忽略，但这其实很重要，因为一般涉及到系统间协同的API，往往不会使用普通的文本，比较常见的是使用json表达复杂结构，而这与通常的缺省理解不同（缺省一般会认为是text/plain和text/html），所以如果在API中忘记用Content-Type进行区分的话，后续对多种类型的客户端接入的支持就会变成陷阱（我们多次遇到过这个问题）。而如果一开始就检查是否增加先验知识（缺省Content-Type为plain或者允许指定Content-Type），那这一困难就可以避免了。
丁雪丰：首先，应该正确地使用HTTP的统一接口，比如HTTP的动词，如果不分青红皂白清一色POST那显然还有改进的余地；
其次，资源有合适的粒度，可以从三个方面来评判资源的粒度是否合理——网络的效率、表述的大小以及客户端使用时的易用程度；
最后，是表述的设计，除了表述的正文内容，还有其中的URI和链接，这些都是评判一个RESTful API好坏的标准。
马钧：在我看来，一个好的API标准，就是能尽量利用到HTTP协议的特性，将HTTP当成一种转移协议，而不是传输协议。包括但不限于：利用HTTP的各种动词来明确操作；包含有内容协商，可以根据请求头提供的参数选择一个资源最合适的媒体类型、语言、字符集和编码的表现；使用不同的返回代码来描述各种状态。但实际上见到过的很多声称RESTful API，包括国内的和国外的，能符合这些条件的并不多。parse.com提供的API是我见到过的较为不错的RESTful API，可以作为范例参考。
InfoQ：安全是恒久的话题，对于基于WSDL和SOAP的Web Service，我们有WS-Security这样的安全规范来指导实现认证、授权、身份管理等安全需求。那么，RESTful API有无成熟可用规范或实现框架呢？如何保证RESTful API的安全性呢？
李锟：保证RESTful API的安全性，主要包括三大方面：
a) 对客户端做身份认证
b) 对敏感的数据做加密，并且防止篡改
c) 身份认证之后的授权
对客户端做身份认证，有几种常见的做法：
在请求中加签名参数
为每个接入方分配一个密钥，并且规定一种签名的计算方法。要求接入方的请求中必须加上签名参数。这个做法是最简单的，但是需要确保接入方密钥的安全保存，另外还要注意防范replay攻击。其优点是容易理解与实现，缺点是需要承担安全保存密钥和定期更新密钥的负担，而且不够灵活，更新密钥和升级签名算法很困难。
使用标准的HTTP身份认证机制
HTTP Basic身份认证安全性较低，必须与HTTPS配合使用。HTTP Digest身份认证可以单独使用，具备中等程度的安全性。
HTTP Digest身份认证机制还支持插入用户自定义的加密算法，这样可以进一步提高API的安全性。不过插入自定义加密算法在面向互联网的API中用的不是很多。
这个做法需要确保接入方“安全域-用户名-密码”三元组信息的安全保存，另外还要注意防范replay攻击。
优点：基于标准，得到了广泛的支持（大量HTTP服务器端、客户端库）。在服务器端做HTTP身份认证的职责可以由Web Server（例如Nginx）、App Server（例如Tomcat）、安全框架（例如Spring Security）来承担，对应用开发者来说是透明的。HTTP身份认证机制（RFC 2617）非常好地体现了“分离关注点”的设计原则，而且保持了操作语义的可见性。
缺点：这类基于简单用户名+密码机制的安全性不可能高于基于非对称密钥的机制（例如数字证书）。
使用OAuth协议做身份认证
OAuth协议适用于为外部应用授权访问本站资源的情况。其中的加密机制与HTTP Digest身份认证相比，安全性更高。需要注意，OAuth身份认证与HTTP Digest身份认证之间并不是相互取代的关系，它们的适用场景是不同的。OAuth协议更适合于为面向最终用户维度的API提供授权，例如获取隶属于用户的微博信息等等。如果API并不是面向最终用户维度的，例如像七牛云存储这样的存储服务，这并非是OAuth协议的典型适用场景。
对敏感的数据做加密，并且防止篡改，常见的做法有：
部署SSL基础设施（即HTTPS），敏感数据的传输全部基于SSL。
仅对部分敏感数据做加密（例如预付费卡的卡号+密码），并加入某种随机数作为加密盐，以防范数据被篡改。
身份认证之后的授权，主要是由应用来控制。通常应该实现某种基于角色+用户组的授权机制，这方面的框架有不少（例如Spring Security），不过大多数开发团队还是喜欢自己来实现相关功能。
李建业：我不认为安全是RESTful API需要考虑的问题，事实上我觉得这是两个正交的问题。当然，如果使用RESTful API来提供认证、授权和身份管理，那也算是双方有关系，但是这和其它风格的API设计所要考虑的问题似乎没什么区别，不值得特别注意。
但是在具体设计层面，这两者的“正交点”上似乎确实有些问题，因为REST是一个推崇状态无关原则的架构风格，而认证和授权通常基于第三方解决方案，所以往往会出现违背有状态约束的问题，这个地方我也没有特别的想法，当然这个困难和原问题关系不大。
至于WS-族的协议，我不太了解，不太能参与讨论。
丁雪丰：对于RESTful API，常见的安全措施都是可以继续使用的。例如，为了防篡改，可以对全部参数进行签名；为了防范重放攻击可以在请求中增加一次性的Token，或者短时间内有效的Token；对内容加密可以实现数据防泄露……；对于DDoS攻击，各种HTTP流量清洗策略，都可以继续发挥作用，因为这就是基本的HTTP请求。
在授权和认证方面，OAuth 2.0已经基本成熟了，并且得到了广泛地应用。如果可以，接入第三方账户体系是个不错的选择，比如Google和Facebook的，国内的当然也有几个候选。
马钧：个人认为RESTful的安全性分为几个层次，在安全要求较高的场合，可以通过HTTPs这样的加密协议来保证网络层的安全，应用层的安全可以通过OAuth实现认证，而对于资源的访问授权，则只能依靠应用程序来实现了。
InfoQ：如何对RESTful API进行版本控制，请分享您认为实用的做法？
李锟：一个比较简单实用的做法是直接在URI中插入版本号，这样做允许多个版本的API并行运行。
另一个做法是在HTTP请求中加入自定义头信息，标明使用的版本号。不过这个做法其实对浏览器不够友好，简单地使用浏览器+HTML无法测试。
李建业：目前比较好的方式还是在uri设计中添加版本信息，其它方法都不如这个实用。
丁雪丰：个人认为最好的版本化，就是没有明显的版本。在对已发布的服务进行变更时，要尽量做到兼容，其中包括URI、链接和各种不同的表述的兼容，最关键的就是在扩展时不能破坏现有的客户端。例如，要变更一个参数，可以选择同时兼容新旧两种输入，或者保持老参数不动，提供一个新的参数，在文档中必须做出说明，不推荐新用户再继续使用之前的参数。
如果必须要进行不兼容的变更，那么可以选择标记不同的版本号，这时可以选择在路径或参数中增加版本信息。也有做法是增加HTTP标头，只是在调用时会稍有不便，推荐前两种方法。
马钧：RESTfulAPI的版本升级，尽量兼容之前的版本，保证原有的API都能正常工作，可以通过HTTP 301转跳到新的资源。另外一种实用的做法就是在url中保留版本号，同时提供多个版本供客户端使用，如 v1.rest.com 或者 rest.com/v1/ 这样。
InfoQ：HTTP1.1规范中给出的动词对于设计RESTful API够用吗？您在实际项目中会扩展自己的动词吗？在什么情况下需要扩展？
李锟：这个问题取决于设计者如何看待和设计资源。如果资源抽象做的很好，对于某个资源的任何操作，通常都能够映射到CRUD四个类别中。CRUD四个类别对于操作资源来说，绝大多数情况下是完备的。HTTP的GET/POST/PUT/DELETE四个方法，对于CRUD四个类别的操作来说是足够的，映射关系是Create-POST/Retrieve-GET/Update-PUT/Delete-DELETE。
我们通常不会选择创建自己的动词，这样做对于客户端开发者来说，需要更多的学习成本。如果在资源上定义的操作过多，我们会选择拆分出更多的资源。
李建业：一般是够用的，有时一些“不够用”的场景是由于我们没有设计出合理的资源，比如批量操作。但是，正如之前所说的那样，对于某些内部的、传统的（因此模型稳定且已知）系统，API提供者和调用者会有自已的固定动词表，此时没必要拘泥。另外，我不建议扩展动词，一旦扩展了动词，其实已经破坏了我之前说的*“尽可能少的先验信息”*，那么，扩展动词和重新设计动词的成本差别不大。基于这个考虑，我建议尽可能保持动词不变，除非你想重新设计动词表。
丁雪丰：一般情况下，常用的HTTP动词是够用的，并没有出现一定要自己扩展动词的情况。其实，最常用的也就是GET、POST、DELETE和PUT，而HEAD、OPTIONS、TRACE则基本用不太到。如果出现一时找不到合适的动词，安全幂等的操作用GET，其他都可以用POST，在设计资源时稍加考虑即可。
马钧：在我的实际项目中，只用到了POST，PUT，DELETE，GET这四个动词。
InfoQ：今年5月份发布的JAX-RS 2.0规范对于RSTfulAPI的设计最有价值的特性是哪个（些）? 它（们）用于解决什么问题？
李锟：REST开发框架RESTEasy项目负责人Bill Burke，去年写了一篇文章介绍JAX-RS 2.0。
我同意Bill在文章中的观点，在JAX-RS 2.0增加的内容中，最重要的三部分为：
a) Client API——用来规范化JAX-RS客户端的开发方式。
b) Server-side Asynchronous HTTP——用来实现服务器端推送功能，而不需要依靠低效的轮询方式。
c) Filters and Interceptors——用来分离关注点，将鉴权、日志等逻辑与业务逻辑分离开，更好地实现代码重用。
这三部分的内容对于开发者来说都很有用。遵循JAX-RS规范做开发，可以确保服务器端以及客户端代码的可移植性。
李建业：我个人关注异步API这部分，主要是因为流式服务将会越来越多，那将大量需要这类支持。
InfoQ：能否为InfoQ的读者推荐一款实用的RESTful API开发框架，并说明您的推介理由。
李锟：这个问题我就不详细回答了。不同的编程语言有不同的REST开发框架，对于REST的支持程度也不同。开发RESTful API的需求范围很广，可选择的开发框架的范围也很广。保持多样性是繁荣生态环境的基础。像Java就有支持JAX-RS规范的Jersey、RESTEasy、Restlet、Apache CXF，和不支持JAX-RS规范的Spring MVC等等很多框架。这些框架目前都做的不错。我对框架的选择没有倾向性。RESTful API设计的最佳实践应该是通用的，而不是必须依赖某种特定的开发框架。
李建业：不好意思，这个我不太重视，没法推荐，不过我可以解释一下为什么对RESTful API框架不感冒的原因。
REST作为一个架构风格，对我们的系统开发有很大影响，但是这些影响一般是针对架构（例如状态无关）或者设计（例如资源识别）上的，所以一旦涉及到具体实现，主要工作就基本结束了，此时开发框架能做的事也就只有简化编程了（相较而言，有的框架还能起到引导设计的作用），而由于RESTful会抽象动词，所以实现层面中和API规范相关的工作本来就不多，那么框架的价值就更小了。
当然，我们也不可能直接基于servlet/rakc/wsgi来开发，不过一般的编程语言都会提供一些简单的url route/match策略，我们使用这些就足够了。另外，有些框架能帮我们生成全部的动词支持，但这也未必是好事，我一般倾向于按需实现——用到了再支持，这就更不需要太关注开发框架对RESTful的支持了。
丁雪丰：由于本人是Spring的拥护者，工作中也一直在使用Spring，所以在选择框架时会更多地倾向Spring MVC（并不是说别的框架不好，这里有些个人主观的成份）。如果一定要选择其他框架，也要选择能够方便与Spring集成的框架。如果在项目中已经使用了Spring，那么没有什么理由不选择Spring MVC，鉴于目前Spring在各种项目中的高出镜率，相信一般情况下都会选择Spring MVC。
REST的成熟度模型中，第三层就是HATEOAS，Spring目前还提供了Spring Hateoas子项目，对链接、资源等方面的支持都做了一定的增强。
马钧：我目前在实际项目中使用的是Spray，这是一个开源的 REST/HTTP 工具包和底层网络 IO 包，基于 Scala 和 Akka 构建。轻量级、异步、非堵塞、基于 actor 模式、模块化和可测试是Spray的特点。
InfoQ：HTTP2.0规范正在制定当中，您对它的期待是什么？
李锟：我的期待包括两个方面：应该做的和不应该做的。
HTTP/2.0规范应该做的：
与HTTP/1.1协议保持兼容。兼容的含义是说两者可以并存，客户端应用可以根据服务器端的能力，自由地选择使用HTTP/2.0还是HTTP/1.1，而且选择过程对应用来说是透明的。
改进HTTP协议（作为资源的统一接口）之中操作语义表达方式的语法，提高网络传输效率。
更好地模块化，这样HTTP/2.0协议的实现能够更好地模块化。应用程序可根据需要选择适当的模块，而不是要么全有、要么全无。
废弃掉HTTP/1.1协议中一些很少有人用到的部分，例如采用管道（pipelining）方式发送请求。
增加更多的动词，以适应除CRUD之外的其他场景。
HTTP/2.0规范不应该做的：
HTTP/2.0协议不应该把底层的数据加密机制（即SSL）作为必选项。
HTTP/2.0协议不应该背离REST架构风格的约束，尤其是要确保操作语义对于中间组件的可见性。
在上面这两个方面，Roy Fileidng曾经与SPDY协议设计者Mike Belshe发生过激烈争论，详情请看：Roy Fielding谈Google SPDY协议
李建业：对此规范关注不多，不知道会不会有对于流的支持，目前我所知道的只有chunk方式进行简单的支持，但是真正的流需要区分数据通道和控制通道——哪怕是逻辑上的区分，这样就直接对REST风格产生了很大冲击，考虑到流式服务在未来的发展潜力，我特别期待业界在这方面有所进展。
丁雪丰：HTTP 2.0很大程度上是借鉴了Google的SPDY，就我而言，首先，希望这个规范能做到与HTTP 1.1的兼容，使用者如果只认识1.1，那么2.0能优雅“降级”；其次，希望2.0能带来更好的性能，SPDY在这方面还是有所改进的，希望HTTP 2.0能再接再厉；最后，希望这个规范能在最终定稿时附带一个最佳实践，正确引导人们合理地使用HTTP 2.0。
马钧：没研究过，估计即使出来，1.1还有很长的生命周期，不会很快被取代。
三种方法实现调用Restful接口
1、基本介绍
Restful接口的调用，前端一般使用ajax调用，后端可以使用的方法比较多，
本次介绍三种：
1）、 HttpURLConnection实现
2）、 HttpClient实现
3）、 Spring的RestTemplate
2、HTTPURLConnection实现
3、HttpClient实现
4、String的RestTemplate实现
springmvc.xml增加
controller
如何做一个api接口？
我们知道API其实就是应用程序编程接口，可以把它理解为是一种通道，用来和不同软件系统间进行通信，本质上它是预先定义的函数。API有很多种形式，最为常见的就是以HTTP协议来提供服务（如：RESTful），只要符合规范就可正常使用。现在各类企业在信息化这块都会用到第三方提供的API，也会提供API给第三方调用，因此设计API也是需要慎重的。
具体该如何开发设计一个良好的API接口呢？
明确功能
在设计之初就需要将API详细功能整理出来，按业务功能点或模块来划分，明确此API需要提供哪些功能。
代码逻辑清晰
保持代码整洁性，增加必要的注释，接口确保功能单一，如果一个接口需要复杂的业务逻辑，建议拆分成多个接口或者将功能独立封装成公共方法，避免接口里代码过多，不利于后期人员维护和后期迭代。
必要的安全校验机制
目前Web应用很容易遭遇数据窃取、篡改、非法提交、重复请求等安全问题，API的安全校验机制是必不可少的。常用解决方案就是采用数字签名形式，将每个HTTP请求都加上签名，服务器端校验签名合法性来保证请求是否合法。
日志记录
为便于及时定位问题，日志是必不可少的。
降低耦合度
一个良好的API应该是越简单越好，如果API间业务耦合度过高很容易因某块代码异常导致相关API的不可用，尽可能避免API间的复杂调用关系。
返回有意义的状态码
API返回数据中要携带状态码数据，比如200代表请求正常，500代表服务器内部错误等。返回通用的状态码有利于问题定位，比如可参考以下状态码：
开发文档
既然API是提供给第三方或内部使用的，那开发文档是必不可少的，否则他人不知道如何调用。一个良好的API开发文档应包含以下元素：
1、当前API架构模式讲解、开发工具及版本、系统依懒等环境信息；
2、当前API提供哪些功能；
3、API模块间的依懒关系；
4、调用规则、注意事项；
5、部署注意事项等。
一个好的API必然是易使用，易看懂，易扩展，难误用，安全性高，功能强大的API。要做到上面几点并不容易，但是我们应当遵从上述原则结合业务本身合理的划分设计API
如何设计好的RESTful API
一个好的RESTful API，应该具备以下特征：
这个API应该是对浏览器友好的，能够很好地融入Web，而不是与Web格格不入。
1.浏览器是最常见和最通用的REST客户端。好的RESTful API应该能够使用浏览器+HTML完成所有的测试（不需要使用编程语言）。这样的API还可以很方便地使用各种自动化的Web功能测试、性能测试工具来做测试。Web前端应用（基于浏览器的RIA应用、移动App等等）也可以很方便地将多个RESTful API的功能组合起来，建造Mashup类的应用。
这个API中所包含的资源和对于资源的操作，应该是直观和容易理解的，并且符合HTTP协议的要求。
REST开发又被称作“面向资源的开发”，这说明对于资源的抽象，是设计RESTful API的核心内容。RESTful API建模的过程与面向对象建模类似，是以名词为核心的。这些名词就是资源，任何可命名的抽象概念都可以定义为一个资源。而HTTP协议并不是一种传输协议，它实际提供了一个操作资源的统一接口。对于资源的任何操作，都应该映射到HTTP的几个有限的方法（常用的有GET/POST/PUT/DELETE四个方法，还有不常用的PATCH/HEAD/OPTIONS方法）上面。所以RESTful API建模的过程，可以看作是具有统一接口约束的面向对象建模过程。
按照HTTP协议的规定，GET方法是安全且幂等的，POST方法是既不安全也不幂等的（可以用来作为所有写操作的通配方法），PUT、DELETE方法都是不安全但幂等的。将对资源的操作合理映射到这四个方法上面，既不过度使用某个方法（例如过度使用GET方法或POST方法），也不添加过多的操作以至于HTTP的四个方法不够用。
2.如果发现资源上的操作过多，以至于HTTP的方法不够用，应该考虑设计出更多的资源。设计出更多资源（以及相应的URI）对于RESTful API来说并没有什么害处。
这个API应该是松耦合的。
RESTful API的设计包括了三个循序渐进、由低到高的层次：资源抽象、统一接口、超文本驱动。正是这三个层次确保了RESTful API的松耦合性。
3.当设计面向互联网的API时，松耦合变成了一种“必须有”的强需求。紧耦合的API非常脆弱，一旦公布出去，服务器端和客户端都无法持续进化。尤其是服务器端，公布出去的接口根本不敢改，改了之后，几乎所有客户端应用立即无法正常工作。REST这种架构风格就是紧耦合API的解毒剂，这个话题可以谈的很深，这里就不展开了。感兴趣的读者可以参考《REST实战》。
这个API中所使用的表述格式应该是常见的通用格式
在RESTful API中，对于资源的操作，是通过在服务器端-客户端之间传递资源的表述来间接完成的。资源的表述可以有很多种格式，并且在响应和请求中的资源表述格式也会有所不同。GET/POST响应中的资源表述格式，常见的有HTML、XML、JSON；POST/PUT请求中的资源表述格式，常见的有标准的HTML表单参数、XML、JSON。
4.这些常见表述格式，处理起来非常容易，有大量的框架和库提供支持。所以除非有很合理的要求，通常不需要使用自定义的私有格式。
使用HTTP响应状态代码来表达各种出错情况
HTTP响应状态代码，是HTTP协议这个统一接口中用来表达出错情况的标准机制。响应状态代码分成两部分：status code和reason phase。两部分都是可定制的，也可以使用标准的status code，只定制reason phase。
5.如果一个所谓的“RESTful API”对于任何请求都返回200 OK响应，在响应的消息体中返回出错情况信息，这种做法显然不符合“确保操作语义的可见性”这个REST架构风格的基本要求。
这个API应该对于HTTP缓存是友好的
restful api接口规范
restful api接口规范如下：
1、协议
API与用户的通信协议，总是使用HTTPs协议。
2、域名
应该尽量将API部署在专用域名之下。
如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。
3、版本（Versioning）
应该将API的版本号放入URL。
另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。
4、路径（Endpoint）
路径又称"终点"（endpoint），表示API的具体网址。
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。
举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
RESTful 接口教程
我们现实生活中的协议是指相互遵守的规定，单方面违背，协议不成立。
而在互联网交互的过程中，也存在这许多协议，例如 FTP、HTTP、STMP、TCP/IP 等。
而 HTTP 协议则是 web 服务器 和 web 客户端 达成的一种可靠的数据传输协议，通过 HTTP 可以从遍布全世界的 Web 服务器上将 JPEG 图片，HTML 页面，文本文件，MPEG 电影，WAV 音频文件和其他资源信息块迅速、便捷、可靠地搬移到人们桌面上的 Web 浏览器上去。它能够确保数据在传输的过程当中不会损坏或者产生混乱。这样，对用户来说是个好事，同样对 Internet 应用的开发人员来说也是一件好事。因为我们在开发过程中也不需要担心自己的页面和数据会在传输过程中发生破坏和畸变了。
Web 内容都是 存储在 Web 服务器 上的。Web 服务器所使用的是 HTTP 协议，因此经常会被称为 HTTP 服务器。这些 HTTP 服务器存储了因特网中的数据，如果 HTTP 客户端发出请求的话，它们会提供数据。客户端向服务器发送 HTTP 请求，服务器会在 HTTP 响应中回送所请求的数据。
那么一次请求和响应的过程中发生了什么？
web 服务器是 web 资源的宿主 ，而 web 资源就是我们常见的 web 内容的源头，最简单的 web 资源就是我们服务器中的静态文件：文本文件，HTML 文档，JPEG 图片文件，AVI 文件等等。
当然 web 资源也可以是动态生成的，类似搜索引擎生成的页面，QQ 空间的动态等，总之，所有类型的内容来源都是资源。
因特网上有数千种不同类型的数据类型，HTTP 在传输的过程中为每个传输的数据都打上了名为 MIME 类型的数据类型标签，描述并标记多媒体内容。
web 浏览器请求一个网站的时候往往会发布 多个 HTTP 请求 ，比如我们在浏览一个具有丰富图片的的 web 页面的时候，浏览器会执行一次 HTTP 请求来获取描述页面布局的 HTML，然后发布另外的请求来获取每个嵌入式的图片，这些图片甚至可能位于不同的服务器上。因此，一个 web 页面通常不是单个资源，而是一组资源的集合。
web 服务器会为所有的 HTTP 对象数据附加一个 MIME 类型 ，当浏览器从服务器中取回一个对象的时候，会查看相关的 MIME 类型。看看它是否知道应该如何处理这个对象。对象的类型写在响应的 content-type 头 中；同样，请求的时候浏览器也会告知服务器请求数据类型。
常见的 MIME 类型：
以 application 开头的媒体格式类型：
MIME 参考手册： W3school MINE类型
大部分 URL 都遵循一种标准格式， 这种格式包含三个部分。
URI = Uniform Resource Identifier 统一资源 标志符 URL = Uniform Resource Locator 统一资源 定位符 URN = Uniform Resource Name 统一资源 名称
翻译成人话: URI 是抽象的定义，不管用什么方法表示，只要能定位一个资源，就叫 URI，本来设想的的使用两种方法定位。 1）URL 用地址定位 2）URN 用名称定位
举个例子：去村子找个具体的人（URI）。如果用地址：某村多少号房子第几间房的主人就是 URL， 如果用身份证号 + 名字，去找就是 URN 了。
目前 WEB 上就 URL 流行开了，平常见得 URI 基本都是 URL。
1）HTTP 和 HTTPS 的相同点
2）HTTP 和 HTTPS 的不同之处
3）如何选择 HTTP 和 HTTPS 协议
HTTP 支持几种不同请求和命令，这些命令被称为 HTTP 方法，每条 HTTP 请求报文都包含一个方法。 这个方法会告诉服务器要执行什么动作（获取一个 Web 页面、发送一段信息、删除一个文件等）。
请求方法如下：
状态码分成如下几个系列：
常见的 HTTP 状态码：
从 Web 客户端发往 Web 服务器的 HTTP 报文称为请求报文（request message）。从服务器发往客户端的报文称为响应报文（response message）。
HTTP 报文包括以下三个部分:
以上内容复制自： http://www.cnblogs.com/Joans/p/3956490.html
使用火狐和 chrome 浏览器打开一个网页，找到其中一个网络请求查看报文。
1）协议
2）域名
3）接口版本控制规范
格式规范如下：
更新版本后可以使用 v2、v3 等依次递加。
4）接口路径规范
格式规范如下：
5）接口命名规范
格式规范如下：
6） HTTP 请求方法
格式规范如下：
GET https://api.xxxxx.com/v1/zoos ：列出所有动物园 POST https://api.xxxxx.com/v1/zoos ：新建一个动物园 GET https://api.xxxxx.com/v1/zoos/ID ：获取某个指定动物园的信息 PUT https://api.xxxxx.com/v1/zoos/ID ：更新某个指定动物园的信息（提供该动物园的全部信息） PATCH https://api.xxxxx.com/v1/zoos/ID ：更新某个指定动物园的信息（提供该动物园的部分信息） DELETE https://api.xxxxx.com/v1/zoos/ID ：删除某个动物园 GET https://api.xxxxx.com/v1/zoos/ID/animals ：列出某个指定动物园的所有动物 DELETE https://api.xxxxx.com/v1/zoos/ID/animals/ID ：删除某个指定动物园的指定动物
注意：修改有两个方法 PUT 和 PATCH。
假设 URL 位置有一组数据 UserInfo，包括 UserID、UserName 等 20 个字段 需求：用户修改了 UserName，其他不变 ? 采用 PATCH，仅向 URL 提交 UserName 的局部更新请求 ? 采用 PUT，必须将所有 20 个字段一并提交到 URL，未提交字段被删除 PATCH 的最主要好处：节省网络带宽
7）接口信息过滤
格式规范如下： ?limit=10：指定返回记录的数量 ?offset=10：指定返回记录的开始位置。 ?page=2&per_page=100：指定第几页，以及每页的记录数。 ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。 ?animal_type_id=1：指定筛选条件
参数的设计允许存在冗余，即允许 API 路径和 URL 参数偶尔有重复。比如， GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。
8）请求参数规范
9）接口返回数据
格式规范如下：
status:：接口的执行状态
data：接口的主数据
msg：返回成功或者失败的错误信息
返回数据中的状态码、状态信息，常指具体的业务状态，不建议和 HTTP 状态码混在一起。HTTP 状态，是用来体现 HTTP链路状态情况，如：404-Not Found。HTTP 状态码和 JSON 结果中的状态码，并存尚可，用于体现不同维度的状态。
简单的功能如下：
这里不牵扯到任何 Python 和 Pycharm 的教学，不会的童鞋挪步 Python 开发教程。
参考新浪开放平台 https://open.weibo.com ，基本是国内最为标准的 API 文档之一。
如何设计好的RESTful API
一个好的RESTful API，应该具备以下特征：
这个API应该是对浏览器友好的，能够很好地融入Web，而不是与Web格格不入。
1.浏览器是最常见和最通用的REST客户端。好的RESTful API应该能够使用浏览器+HTML完成所有的测试（不需要使用编程语言）。这样的API还可以很方便地使用各种自动化的Web功能测试、性能测试工具来做测试。Web前端应用（基于浏览器的RIA应用、移动App等等）也可以很方便地将多个RESTful API的功能组合起来，建造Mashup类的应用。
这个API中所包含的资源和对于资源的操作，应该是直观和容易理解的，并且符合HTTP协议的要求。
REST开发又被称作“面向资源的开发”，这说明对于资源的抽象，是设计RESTful API的核心内容。RESTful API建模的过程与面向对象建模类似，是以名词为核心的。这些名词就是资源，任何可命名的抽象概念都可以定义为一个资源。而HTTP协议并不是一种传输协议，它实际提供了一个操作资源的统一接口。对于资源的任何操作，都应该映射到HTTP的几个有限的方法（常用的有GET/POST/PUT/DELETE四个方法，还有不常用的PATCH/HEAD/OPTIONS方法）上面。所以RESTful API建模的过程，可以看作是具有统一接口约束的面向对象建模过程。
按照HTTP协议的规定，GET方法是安全且幂等的，POST方法是既不安全也不幂等的（可以用来作为所有写操作的通配方法），PUT、DELETE方法都是不安全但幂等的。将对资源的操作合理映射到这四个方法上面，既不过度使用某个方法（例如过度使用GET方法或POST方法），也不添加过多的操作以至于HTTP的四个方法不够用。
2.如果发现资源上的操作过多，以至于HTTP的方法不够用，应该考虑设计出更多的资源。设计出更多资源（以及相应的URI）对于RESTful API来说并没有什么害处。
这个API应该是松耦合的。
RESTful API的设计包括了三个循序渐进、由低到高的层次：资源抽象、统一接口、超文本驱动。正是这三个层次确保了RESTful API的松耦合性。
3.当设计面向互联网的API时，松耦合变成了一种“必须有”的强需求。紧耦合的API非常脆弱，一旦公布出去，服务器端和客户端都无法持续进化。
规划好你的API的外观要先于开发它实际的功能。首先你要知道数据该如何设计和核心服务/应用程序会如何工作。如果你纯粹新开发一个API，这样会比较容易一些。但如果你是往已有的项目中增加API，你可能需要提供更多的抽象。
有时候一个集合可以表达一个数据库表，而一个资源可以表达成里面的一行记录，但是这并不是常态。事实上，你的API应该尽可能通过抽象来分离数据与业务逻辑。这点非常重要，只有这样做你才不会打击到那些拥有复杂业务的第三方开发者，否则他们是不会使用你的API的。
当然你的服务可能很多部分是不应该通过API暴露出去的。比较常见的例子就是很多API是不允许第三方来创建用户的。
GET (选择）：从服务器上获取一个具体的资源或者一个资源列表。
POST（创建）：在服务器上创建一个新的资源。
PUT（更新）：以整体的方式更新服务器上的一个资源。
PATCH（更新）：只更新服务器上一个资源的一个属性。
DELETE（删除）：删除服务器上的一个资源。
还有两个不常用的HTTP动词：
HEAD：获取一个资源的元数据，如数据的哈希值或最后的更新时间。
OPTIONS：获取客户端能对资源做什么操作的信息。
一个好的RESTful API只允许第三方调用者使用这四个半HTTP动词进行数据交互，并且在URL段里面不出现任何其他的动词。
一般来说，GET请求可以被浏览器缓存（通常也是这样的）。例如，缓存请求头用于第二次用户的POST请求。HEAD请求是基于一个无响应体的GET请求，并且也可以被缓存的。
Restful接口文档规范
基于目前的大前端时代，对于常年负责后台开发的我来说， 最重要的就是提供稳定的接口和文档。便于小伙伴们进行业务对接。
当下常用的是RestFul风格的定义规范， 之前开发是清一色Get、Post。引入RestFul后感觉接口定义规范很多，看接口地址就知晓是什么功能， 一起来看看列的一些基础规范吧。
API与客户端用户的通信协议，总是使用HTTPS协议，以确保交互数据的传输安全。
应该尽量将API部署在专用域名之下： https://api.example.com
如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下： https://www.example.com/api
https://api.example.com/v{n}
1、应该将API的版本号放入URL。
2、采用多版本并存，增量发布的方式。
3、n代表版本号，分为整型和浮点型
整型： 大功能版本， 如v1、v2、v3 ...
浮点型： 补充功能版本， 如v1.1、v1.2、v2.1、v2.2 ...
4、对于一个 API 或服务，应在生产中最多保留 3 个最详细的版本
路径又称"终点"（end point），表示API的具体网址。
1、在RESTful架构中，每个网址代表一种资源(resource),所以网址中不能有动词，只能有名词。
【所用的名词往往与数据库的表格名对应】
2、数据库中的表一般都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。
例子: https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees
GET（SELECT）： 从服务器取出资源（一项或多项）。
POST（CREATE）： 在服务器新建一个资源。
PUT（UPDATE）： 在服务器更新资源（客户端提供改变后的完整资源）。
DELETE（DELETE）： 从服务器删除资源。
例子：
GET /v1/products 获取所有商品
GET /v1/products/ID 获取某个指定商品的信息
POST /v1/products 新建一个商品
PUT /v1/products/ID 更新某个指定商品的信息
DELETE /v1/products/ID 删除某个商品,更合理的设计详见【9、非RESTful API的需求】
GET /v1/products/ID/purchases 列出某个指定商品的所有投资者
GET /v1/products/ID/purchases/ID 获取某个指定商品的指定投资者信息
若记录数量很多，服务器不可能返回全部记录给用户。
API应该提供分页参数及其它筛选参数，过滤返回结果。
/v1/products?page=1&pageSize=20 指定第几页，以及每页的记录数。
/v1/products?sortBy=name&order=asc 指定返回结果按照哪个属性排序，以及排序顺序。
传入参数分为4种类型：
1、cookie： 一般用于OAuth认证
2、request header： 一般用于OAuth认证
3、请求body数据：
4、地址栏参数：
1）restful 地址栏参数 /v1/products/ID ID为产品编号，获取产品编号为ID的信息
2）get方式的查询字段 见【六、过滤信息】
response：
----------------------------------------
{
status: 200, // 详见【status】
data: {
code: 1, // 详见【code】
data: {} || [], // 数据
message: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】
sysMessage: 'success' // 存放响应信息提示,调试使用,中英文都行
... // 其它参数，如 total【总记录数】等
},
msg: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】
sysMsg: 'success' // 存放响应信息提示,调试使用,中英文都行
}
----------------------------------------
【status】:
200: OK 400: Bad Request 500：Internal Server Error
401：Unauthorized
403：Forbidden
404：Not Found
【code】:
1: 获取数据成功 | 操作成功 0：获取数据失败 | 操作失败
1、实际业务开展过程中，可能会出现各种的api不是简单的restful 规范能实现的。
2、需要有一些api突破restful规范原则。
3、特别是移动互联网的api设计，更需要有一些特定的api来优化数据请求的交互。
1)、删除单个 | 批量删除 ： DELETE /v1/product body参数{ids：[]}
2)、页面级API : 把当前页面中需要用到的所有数据通过一个接口一次性返回全部数据
1、前端需要哪些字段，API接口应该返回哪些字段，字段不多也不少。
2、更新功能尽量做到：初次返回的原始数据参数与提交更新的数据参数结构一致。
3、时间参数，尽量以一致格式的字符串传递， 如：
‘2019-01’ | ‘2019/01’
‘2019-01-01’ | ‘2019/01/01’
‘2019-01-01 12:12:12’ | ‘2019/01/01 12:12:12’
1、尽量采用自动化接口文档，可以做到在线测试，同步更新。
2、应包含：接口BASE地址、接口版本、接口模块分类等。
3、每个接口应包含：
接口地址：不包含接口BASE地址。
请求方式: get、post、put、delete等。
请求参数：数据格式【默认JSON、可选form data】、数据类型、是否必填、中文描述。
相应参数：类型、中文描述。