RESTful概念RESTRepresentational StateTransfer表象化状态转变表述性状态转变在2000年被提出基于HTTP、URI、XML、JSON等标准和协议支持轻量级、跨平台、跨语言的架构设计。是Web服务的一种新的架构风格一种思想。RESTful 一种软件架构风格、设计风格而不是标准只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁更有层次更易于实现缓存等机制。RESTful只是一种架构方式的约束给出一种约定的标准完全严格遵守RESTful标准并不是很多也没有必要。但是在实际运用中有RESTful标准可以参考是十分有必要的。实际上在工作中对api接口规范、命名规则、返回值、授权验证等进行一定的约束一般的项目api只要易测试、足够安全、风格一致可读性强、没有歧义调用方便我觉得已经足够了接口是给开发人员看的也不是给普通用户去调用。REST架构的主要原则对网络上所有的资源都有一个资源标志符。客户端通过四个HTTP动词get、post、put、delete对服务器端资源进行操作实现”表现层状态转化”同一资源有多种表现形式xml、json所有操作都是无状态的StatelessURL定义资源互联网所有的事物都可以被抽象为资源什么是无状态性?使得客户端和服务器端不必保存对方的详细信息服务器只需要处理当前的请求不需了解请求的历史。可以更容易的释放资源让服务器利用Pool连接池技术来提高稳定性和性能。RESTful的7个最佳实践1. 版本如github开放平台https://developer.github.com/v3/就是将版本放在url简洁明了这个只有用了才知道一般的项目加版本v1v2v3?好吧这个加版本估计只有大公司才会去使用.https://example.com/api/v1/2.参数命名规范query parameter可以采用驼峰命名法也可以采用下划线命名的方式推荐采用下划线命名的方式据说后者比前者的识别度要高可能是用的人多了吧因人而异因团队规范而异吧。https://example.com/api/users/today_login 获取今天登陆的用户 https://example.com/api/users/today_loginsortlogin_desc 获取今天登陆的用户、登陆时间降序排列3.url命名规范API 命名应该采用约定俗成的方式保持简洁明了。在RESTful架构中每个url代表一种资源所以url中不能有动词只能有名词并且名词中也应该使用复数。实现者应使用相应的Http动词GET、POST、PUT、PATCH、DELETE、HEAD来操作这些资源即可不规范的的url冗余没有意义形式不固定不同的开发者还需要了解文档才能调用。安全性和幂等性安全性不会改变资源状态可以理解为只读的幂等性执行1次和执行N次对资源状态改变的效果是等价的。4. 统一返回数据格式对于合法的请求应该统一返回数据格式这里演示的是jsoncode——包含一个整数类型的HTTP响应状态码。status——包含文本”success””fail”或”error”。HTTP状态响应码在500-599之间为”fail”在400-499之间为”error”其它均为”success”例如响应状态码为1XX、2XX和3XX。这个根据实际情况其实是可要可不要的。message——当状态值为”fail”和”error”时有效用于显示错误信息。参照国际化il8n标准它可以包含信息号或者编码可以只包含其中一个或者同时包含并用分隔符隔开。data——包含响应的body。当状态值为”fail”或”error”时data仅包含错误原因或异常名称、或者null也是可以的返回成功的响应json格式{code:200,message:success,data:{userName:123456,age:16,address:beijing}}返回失败的响应json格式{code:401,message:error message,data:null}5. http状态码1** 请求未成功2** 请求成功、表示成功处理了请求的状态代码。3** 请求被重定向、表示要完成请求需要进一步操作。 通常这些状态代码用来重定向。4** 请求错误这些状态代码表示请求可能出错妨碍了服务器的处理。5**服务器错误这些状态代码表示服务器在尝试处理请求时发生内部错误。 这些错误可能是服务器本身的错误而不是请求出错。6. 合理使用query parameter在请求数据时客户端经常会对数据进行过滤和分页等要求而这些参数推荐采用HTTP Query Parameter的方式实现比如设计一个最近登陆的所有用户 https://example.com/api/users?recently_login_day3搜索用户并按照注册时间降序 https://example.com/api/users?recently_login_day3搜索用户并按照注册时间升序、活跃度降序 https://example.com/api/users?qkeysortcreate_title_asc,liveness_desc7. 多表、多参数连接查询如何设计URL这是一个比较头痛的问题在做单个实体的查询比较容易和规范操作但是在实际的API并不是这么简单而已这其中常常会设计到多表连接、多条件筛选、排序等。比如我想查询一个获取在6月份的订单中大于500元的且用户地址是北京用户年龄在22岁到40岁、购买金额降序排列的订单列表https://example.com/api/orders?order_month6order_amount_greater500address_city北京sortorder_amount_descage_min22age_max40从这个URL上看参数众多、调用起来还得一个一个仔细对着而且API本身非常不容易维护命名看起来不是很容易不能太长也不能太随意。在.net WebAPI总我们可以使用属性路由属性路由就是讲路由附加到特定的控制器或操作方法上装饰Controll及其使用[Route]属性定义路由的方法称为属性路由。这种好处就是可以精准地控制URL而不是基于约定的路由简直就是为这种多表查询量身定制似的的。 从webapi 2开发现在是RESTful API开发中最推荐的路由类型。我们可以在Controll中标记Route[Route(“api/orders/{address}/{month}”)]Action中的查询参数就只有金额、排序、年龄。减少了查询参数、API的可读性和可维护行增强了。https://example.com/api/orders/beijing/6?order_amount_greater500sortorder_amount_descage_min22age_max40这种属性路由比如在博客园开放的API也有这方面的应用如获取个人博客随笔列表请求方式GET请求地址https://api.cnblogs.com/api/blogs/{blogApp}/posts?pageIndex{pageIndex}(ps:blogApp博客名) RESTful--介绍
RESTful概念RESTRepresentational StateTransfer表象化状态转变表述性状态转变在2000年被提出基于HTTP、URI、XML、JSON等标准和协议支持轻量级、跨平台、跨语言的架构设计。是Web服务的一种新的架构风格一种思想。RESTful 一种软件架构风格、设计风格而不是标准只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁更有层次更易于实现缓存等机制。RESTful只是一种架构方式的约束给出一种约定的标准完全严格遵守RESTful标准并不是很多也没有必要。但是在实际运用中有RESTful标准可以参考是十分有必要的。实际上在工作中对api接口规范、命名规则、返回值、授权验证等进行一定的约束一般的项目api只要易测试、足够安全、风格一致可读性强、没有歧义调用方便我觉得已经足够了接口是给开发人员看的也不是给普通用户去调用。REST架构的主要原则对网络上所有的资源都有一个资源标志符。客户端通过四个HTTP动词get、post、put、delete对服务器端资源进行操作实现”表现层状态转化”同一资源有多种表现形式xml、json所有操作都是无状态的StatelessURL定义资源互联网所有的事物都可以被抽象为资源什么是无状态性?使得客户端和服务器端不必保存对方的详细信息服务器只需要处理当前的请求不需了解请求的历史。可以更容易的释放资源让服务器利用Pool连接池技术来提高稳定性和性能。RESTful的7个最佳实践1. 版本如github开放平台https://developer.github.com/v3/就是将版本放在url简洁明了这个只有用了才知道一般的项目加版本v1v2v3?好吧这个加版本估计只有大公司才会去使用.https://example.com/api/v1/2.参数命名规范query parameter可以采用驼峰命名法也可以采用下划线命名的方式推荐采用下划线命名的方式据说后者比前者的识别度要高可能是用的人多了吧因人而异因团队规范而异吧。https://example.com/api/users/today_login 获取今天登陆的用户 https://example.com/api/users/today_loginsortlogin_desc 获取今天登陆的用户、登陆时间降序排列3.url命名规范API 命名应该采用约定俗成的方式保持简洁明了。在RESTful架构中每个url代表一种资源所以url中不能有动词只能有名词并且名词中也应该使用复数。实现者应使用相应的Http动词GET、POST、PUT、PATCH、DELETE、HEAD来操作这些资源即可不规范的的url冗余没有意义形式不固定不同的开发者还需要了解文档才能调用。安全性和幂等性安全性不会改变资源状态可以理解为只读的幂等性执行1次和执行N次对资源状态改变的效果是等价的。4. 统一返回数据格式对于合法的请求应该统一返回数据格式这里演示的是jsoncode——包含一个整数类型的HTTP响应状态码。status——包含文本”success””fail”或”error”。HTTP状态响应码在500-599之间为”fail”在400-499之间为”error”其它均为”success”例如响应状态码为1XX、2XX和3XX。这个根据实际情况其实是可要可不要的。message——当状态值为”fail”和”error”时有效用于显示错误信息。参照国际化il8n标准它可以包含信息号或者编码可以只包含其中一个或者同时包含并用分隔符隔开。data——包含响应的body。当状态值为”fail”或”error”时data仅包含错误原因或异常名称、或者null也是可以的返回成功的响应json格式{code:200,message:success,data:{userName:123456,age:16,address:beijing}}返回失败的响应json格式{code:401,message:error message,data:null}5. http状态码1** 请求未成功2** 请求成功、表示成功处理了请求的状态代码。3** 请求被重定向、表示要完成请求需要进一步操作。 通常这些状态代码用来重定向。4** 请求错误这些状态代码表示请求可能出错妨碍了服务器的处理。5**服务器错误这些状态代码表示服务器在尝试处理请求时发生内部错误。 这些错误可能是服务器本身的错误而不是请求出错。6. 合理使用query parameter在请求数据时客户端经常会对数据进行过滤和分页等要求而这些参数推荐采用HTTP Query Parameter的方式实现比如设计一个最近登陆的所有用户 https://example.com/api/users?recently_login_day3搜索用户并按照注册时间降序 https://example.com/api/users?recently_login_day3搜索用户并按照注册时间升序、活跃度降序 https://example.com/api/users?qkeysortcreate_title_asc,liveness_desc7. 多表、多参数连接查询如何设计URL这是一个比较头痛的问题在做单个实体的查询比较容易和规范操作但是在实际的API并不是这么简单而已这其中常常会设计到多表连接、多条件筛选、排序等。比如我想查询一个获取在6月份的订单中大于500元的且用户地址是北京用户年龄在22岁到40岁、购买金额降序排列的订单列表https://example.com/api/orders?order_month6order_amount_greater500address_city北京sortorder_amount_descage_min22age_max40从这个URL上看参数众多、调用起来还得一个一个仔细对着而且API本身非常不容易维护命名看起来不是很容易不能太长也不能太随意。在.net WebAPI总我们可以使用属性路由属性路由就是讲路由附加到特定的控制器或操作方法上装饰Controll及其使用[Route]属性定义路由的方法称为属性路由。这种好处就是可以精准地控制URL而不是基于约定的路由简直就是为这种多表查询量身定制似的的。 从webapi 2开发现在是RESTful API开发中最推荐的路由类型。我们可以在Controll中标记Route[Route(“api/orders/{address}/{month}”)]Action中的查询参数就只有金额、排序、年龄。减少了查询参数、API的可读性和可维护行增强了。https://example.com/api/orders/beijing/6?order_amount_greater500sortorder_amount_descage_min22age_max40这种属性路由比如在博客园开放的API也有这方面的应用如获取个人博客随笔列表请求方式GET请求地址https://api.cnblogs.com/api/blogs/{blogApp}/posts?pageIndex{pageIndex}(ps:blogApp博客名)