RESTfull defined
Excerpt from Baidu Encyclopedia entries RESTful .
REST（英文：Representational State Transfer，简称REST）描述了一个架构样式的网络系统，比如 web 应用程序。它首次出现在 2000 年 Roy Fielding 的博士论文中，Roy Fielding是 HTTP 规范的主要编写者之一。在目前主流的三种Web服务交互方案中，REST相比于SOAP（Simple Object Access protocol，简单对象访问协议）以及XML-RPC更加简单明了，无论是对URL的处理还是对Payload的编码，REST都倾向于用更加简单轻量的方法设计和实现。值得注意的是REST并没有一个明确的标准，而更像是一种设计的风格。
REST 指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。
RESTFUL特点包括：
1、每一个URI代表1种资源；
2、客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源；
3、通过操作资源的表现形式来操作资源；
4、资源的表现形式是XML或者HTML；
5、客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。
RESTful standard usage practices
In an example where a logistics system defines a set of interfaces, there needs to be done following functions
- Maintenance logistics waybill. The user needs to perform a single transport stream CRUD operations. Each ship has a single number on a single, carrier, mode of transport and other information.
- Maintain invoice information. Users need to manage invoices, each invoice has weight, and the amount of related logistics waybill number.
- Statistics different modes of transport, cost carrier information in a given time.
By requirements can clearly see two resources, transport logistics and invoice, and are defined as Invoice delivery, according to the characteristics of REST-style, the interface is defined as follows
-
Creating logistics waybill
REST is recommended to create a resource POST
创建物流运单接口 URL:[POST]/delivery Request: { "doNum": "12345678", "carrier": "shunfeng", "mot": "kongyun", "weight": 234 } Response: { "doNum": "12345678", "carrier": "shunfeng", "mot": "kongyun", "weight": 234 }
error code:
-
200: Creating normal
- 409: Number of single conflict
- 422: The parameter is incorrect. Alone error code that is difficult to give a more accurate tips , like this: transportation kongyun error, effective mode of transport [Air, Sea, Truck].
-
Logistics AWB inquiry
REST GET recommended to get the resources.
查询所有： URL:[GET]/delivery Response: [ {运单信息}, {运单信息} ] 根据ID查询 URL:[GET]/delivery/{delivery-id} Response: {运单信息} 多条件查询 URL:[GET]/delivery/?mot={运输方式}&carrier={承运商}... Response: [ {运单信息}, {运单信息} ]error code:
- 200: normal query
- 404: The resource request is absent.
- 422: query parameter is incorrect
In practical applications, this query is up to the challenge
-
Too many parameters difficult to pass
GET conventional way of passing parameters is the URL parameter, but the URL length is limited, it is difficult to complete a similar query 10000 single number this demand.
-
Difficult to pass complex parameters
Passing parameters in a conventional manner is GET URL parameters, but only pass the URL parameters simple configuration data, parameters difficult to handle object array, similar to the [{ "carrier" = "c1", "mot" = "Sea"}, { "carrier" = "c2", "mot" = "Air"}] this complex parameters require special handling. For the file as the filter criteria can not even deal with.
-
Workload and more
Background in dealing with complex queries, usually there is a structure representing a request condition, constructed by URL parameters of this structure requires additional work, the front desk when sending the request, the splicing of all parameters to the URL is also required effort, also faces a variety of coding problems.
-
Modify logistics waybill
PUT REST is recommended to get the resources.
修改物流运单接口 URL:[PUT]/delivery/{delivery-id} Request: { "doNum": "12345678", "carrier": "shunfeng", "mot": "kongyun", "weight": 234 } Response: { "doNum": "12345678", "carrier": "shunfeng", "mot": "kongyun", "weight": 234 }error code:
- 200: normal modification
- 422: Parameter error. And create the same can not be more accurate error reporting.
In practice, this modification operations also face the challenge of bulk editing and partial modification of
-
Batch Edit
The user wishes to modify some of the attributes satisfy all the conditions of the consignment to a fixed value. The demand is very common, but did not say how to do REST, the current developers are essentially free to play.
-
Some changes
Complex business data often involve partial modification. For example, each arrived at a station, there will be a member of weighing goods weighing, weighing results recorded, the person's information is not a class relationship destination, he weighed just add a record on the waybill
-
Delete logistics waybill
REST is recommended to use DELETE to get the resources.
删除物流运单接口 URL:[DELETE]/delivery/{delivery-id} Response: { "doNum": "12345678", "carrier": "shunfeng", "mot": "kongyun", "weight": 234 }There are practical batch delete scenes
-
Bulk upload logistics waybill
REST is not recommended
-
Batch download logistics waybill
REST is not recommended
-
Invoice management interface. Referring to a single transport stream like.
-
Statistics Interface
Statistical information is integrated invoice and waybill data, we called him after sharing the invoice, the invoice amount is information on each individual consignment, referred to as delivery-invoice. In the background there can be a component automatically updated. Although this interface is a query interface, but not the content of the original data query, data statistics, I do not know what should be called a URL.
REST enhance
Technical specifications and are serving the business, driven by business needs, and all the technical specifications must advance with the times. For the above-mentioned problem, we are doing some adjustments.
basic rules
-
Use HTTP Code does not return an error message
HTTP Code shouldering the function of the transport layer, making it part-time business logic, it is actually very difficult. All operations return information are on the Response is more reasonable. So we define a common return structure
{ "error": [], // 使用字符串返回所有严重的影响业务继续执行的错信息 "warning": [], // 使用字符串返回所有警告类业务信息 "message": ... // 根据业务需要返回需要的信息 } -
Extended URI specified resource
URI attribute is still used to locate resources, is now extended the range of resources to existing resources
/delivery // 表示运单资源 /delivery/123 // 表示某一个具体的运单资源 /delivery/123/weight-check // 运单123相关的重量检测记录 /delivery/123/weight-check/1 // 运单123上id为1的重量检测记录 /delivery/mot // 这个不是资源，不能这么写 -
Head through different extensions of Command
In the case of the original can not be expressed in four Method, by increasing REST_Command to extend the functionality of the Head
REST_Command=BATCH_CREATE // 表示批量创建请求 REST_Command=SEARCH // 表示当前操作是一个查询请求 REST_Command=SEARCH_SUMMARY // 表示查询摘要信息，根据业务需要返回比较少的内容，类似只返回运单基本信息，没有重量检测信息 REST_Command=PART_UPDATE // 部分修改。此时修改操作仅仅修改运单数据，不影响重量检测列表 REST_Command=BATCH_UPDATE // 批量修改。 REST_Command=BATCH_DELETE // 批量删除 REST_Command=GENERATE // 对于没有持久化，而是实时计算出来的结果，使用这个命令 -
Request for operational parameters
Business and business-related parameters must service parameters is similar user login information for marking query, modify a class name, not the business information.
Demo
-
Creating logistics waybill
-
Create a waybill
URL:[POST]/delivery Request: { "doNum": "12345678", "carrier": "shunfeng", "mot": "kongyun", "weight": 234 } Response: { "error": [], "warning": [], "message": { "doNum": "12345678", "carrier": "shunfeng", "mot": "kongyun", "weight": 234 } } -
Create a list of transport objects
URL:[POST]/delivery/{delivery-id}/weight-check Request: { "id": 1, "time": "2020-02-02 02:02:02", "weight": 234 } Response: { "error": [], "warning": [], "message": { "id": 1, "time": "2020-02-02 02:02:02", "weight": 234 } }Child objects must be saved with the waybill information, if there is no waybill, the information is gone. AWB detecting the weight recorded to the partial object, but allocated to the waybill invoice is not, is not running, invoices still die.
-
-
Bulk create
创建物流运单接口 URL:[POST]/delivery Head: REST_Command=BATCH_CREATE Request: { // 这个request可以根据需求做一些定制 "doNum": ["12345678", "1234569"], "carrier": "shunfeng", "mot": "kongyun", "weight": 234 } Response: { "error": [], "warning": [], "message": [{ "doNum": "12345678", "carrier": "shunfeng", "mot": "kongyun", "weight": 234 }, ...] } -
Logistics AWB inquiry
-
All inquiries
URL:[GET]/delivery Head: REST_Command=SEARCH;SEARCH_SUMMARY; // 不同的命令返回数据不同 Response: { "error": [], "warning": [], "message": [{运单信息}, {运单信息}] } -
According to a single query ID
URL:[GET]/delivery/{delivery-id} Head: REST_Command=SEARCH;SEARCH_SUMMARY; // 不同的命令返回数据不同 Response: { "error": [], "warning": [], "message": { "doNum": "12345678", "carrier": "shunfeng", "mot": "kongyun", "weight": 234, "weightCheck": [{ "id": 1, "time": "2020-02-02 02:02:02", "weight": 234 } ] } } -
Complex queries Conditions
URL:[POST]/delivery Head: REST_Command=SEARCH;SEARCH_SUMMARY; // 不同的命令返回数据不同 Request: { "mot": ["haiyun", "kongyun"], "carrier": ["承运商1", "承运商2"] } Response: { "error": [], "warning": [], "message": [{运单信息}, {运单信息}] } -
Queries sub-object list
URL:[GET]/delivery/{delivery-id}/weight-check/{check-id} Response: { "error": [], "warning": [], "message": [{重量检测信息}, {重量检测信息}] }
-
-
Modify logistics waybill
-
The full amount of modification waybill
URL:[PUT]/delivery/{delivery-id} Request: { "doNum": "12345678", "carrier": "shunfeng", "mot": "kongyun", "weight": 234 } Response: { "error": [], "warning": [], "message": {运单信息} } -
Partially modified waybill
URL:[PUT]/delivery/{delivery-id} Head: REST_Command=PART_UPDATE Request: { "doNum": "12345678", "carrier": "shunfeng", "mot": "kongyun", "weight": 234 } Response: { "error": [], "warning": [], "message": {运单信息} } -
Modify the list of transport objects
URL:[PUT]/delivery/{delivery-id}/weight-check/1 Request: { "id": 1, "time": "2020-02-02 02:02:02", "weight": 234 } Response: { "error": [], "warning": [], "message": { "id": 1, "time": "2020-02-02 02:02:02", "weight": 234 } } -
Bulk edit waybill
URL:[PUT]/delivery/ Head: REST_Command=BATCH_UPDATE Request: { // 业务自定义请求内容 "doNum": ["12345678", "12345679"] "carrier": "shunfeng", "mot": "kongyun", "weight": 234 } Response: { "error": [], "warning": [], "message": [{运单信息}] }
-
-
Delete logistics waybill
Delete operation returns directly when deleting object does not exist, because expectations consistent results and current results.
-
Delete waybill
URL:[DELETE]/delivery/{delivery-id} Response: { "error": [], "warning": [], "message": [{运单信息}] } -
Delete list of transport objects
URL:[DELETE]/delivery/{delivery-id}/weight-check/{check-id} Response: { "error": [], "warning": [], "message": [{重量检测信息}] } -
batch deletion
URL:[POST]/delivery Head: REST_Command=BATCH_DELETE Request: { "mot": ["haiyun", "kongyun"], "carrier": ["承运商1", "承运商2"] } Response: { "error": [], "warning": [], "message": [{运单信息}, {运单信息}] }
-
-
Bulk upload logistics waybill
Bulk upload can be done according to the interface created in batches. Update REST_Command = BATCH_UPLOAD.
-
Batch download logistics waybill
Batch download can be done according to the interface batch queries. Update REST_Command = DOWNLOAD.
-
Statistics Interface
Statistical information is integrated invoice and waybill data, we called him after sharing the invoice, the invoice amount is information on each individual consignment, referred to as delivery-invoice. In the background there can be a component automatically updated. Although this interface is a query interface, but not the content of the original data query, statistical data, so named for the delivery-invoice-report.
URL:[POST]/delivery-invoice-report Head: REST_Command=GENERATE Request: { // 自定义查询条件 "mot": ["haiyun", "kongyun"], "carrier": ["承运商1", "承运商2"] } Response: { "error": [], "warning": [], "message": {统计结果} }
to sum up
- URI represents fixed resources, sub-objects are also considered resource, calculated in real time using a virtual content resource
- HTTP Code content transmission layer is no longer involved in the business logic
- Use common Response structure to return various error messages
- Extended Head, increase REST_Command complete a variety of diverse functions
