工程服务

Rest API

REST中定义工程对外，提供的服务。

• HTTP动词

  常用的HTTP动词如下（括号里是对应的SQL命令）：

  • GET（SELECT）：从服务器取出一项或多项资源。
  • POST（CREATE）：在服务器新建一个资源。
  • PUT（UPDATE）：客户端提供改变后的完整资源，在服务器更新资源。
  • PATCH（UPDATE）：客户端提供改变的属性，在服务器更新资源。
  • DELETE（DELETE）：从服务器删除资源。
• 资源路径
  • URL中不能有动词

    在Restful架构中，每个网址代表的是一种资源，所以网址中不能有动词，只能有名词，动词由HTTP的动作来表示。

  • URL结尾不应该包含斜杠“/”

    正斜杠（/）不会增加语义值，且可能导致混淆。

  • 正斜杠分隔符“/”必须用来指示层级关系

    路径中的正斜杠“/”字符，用于指示资源之间的层次关系。

  • 应该使用连字符“-”来提高URL的可读性，而不是使用下划线“_”

    一些文本查看器为了区分强调URL，经常会在URL下加上下划线。这样下划线“_”字符可能被文本查看器中，默认的下划线部分的遮蔽或完全隐藏。为避免这种混淆，请使用连字符而不是下划线。

  • URL路径中首选小写字母

    URL是对大小写敏感的，所以为了避免歧义，尽量用小写字符。

    补充说明：主机名（Host）和scheme（协议名称:http/ftp/...）对大小写是不敏感的。

  • 应该将API的版本号放入URL

    另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。

  • URL路径名词均为复数

    为了保证URL格式的一致性，建议使用复数形式。

• 响应状态码
  • 200 | OK ：用于一般性的成功返回。
  • 201 | Created [POST/PUT/PATCH]：用户新建或修改数据成功。
  • 202 | Accepted：用于Controller控制类资源异步处理的返回，仅表示请求已经收到。对于耗时比较久的处理，一般用异步处理来完成。
  • 204 | No Content：此状态可能会出现在PUT、POST、DELETE的请求中，一般表示资源存在，但消息体中不会返回任何资源相关的状态或信息。
  • 301 | Moved Permanently：资源的URI被转移，需要使用新的URI访问。
  • 302 | Found：不推荐使用，此代码在HTTP 1.1协议中被303/307替代。目前对302的使用和最初HTTP 1.0定义的语意是有出入的，应该只有在GET/HEAD方法下，客户端才能根据Location执行自动跳转，而目前的客户端基本上是不会判断原请求方法的，无条件的执行临时重定向。
  • 303 | See Other： 返回一个资源地址URI的引用，但不强制要求客户端获取该地址的状态（访问该地址）。
  • 304 | Not Modified：有一些类似于204状态，服务器端的资源与客户端最近访问的资源版本一致，并无修改，不返回资源消息体。可以用来降低服务端的压力。
  • 307 | Temporary Redirect： 目前URI不能提供当前请求的服务，临时性重定向到另外一个URI。在HTTP 1.1中307是用来替代早期HTTP 1.0中使用不当的302。
  • 400 | Bad Request：用于客户端一般性错误返回，在其它4xx错误以外的错误，也可以使用400，具体错误信息可以放在body中。
  • 401 | Unauthorized： 在访问一个需要验证的资源时，验证错误。
  • 403 | Forbidden：一般用于非验证性资源访问被禁止，例如对于某些客户端只开放部分API的访问权限，而另外一些API可能无法访问时，可以给予403状态。
  • 404 | Not Found：找不到URI对应的资源。
  • 405 | Method Not Allowed：HTTP的方法不支持，例如某些只读资源，可能不支持POST/DELETE。但405的响应header中必须声明该URI所支持的方法。
  • 406 | Not Acceptable：客户端所请求的资源数据格式类型不被支持，例如客户端请求数据格式为application/xml，但服务器端只支持application/json。
  • 409 | Conflict： 资源状态冲突，例如客户端尝试删除一个非空的Store资源。
  • 412 | Precondition Failed：用于有条件的操作不被满足时。
  • 415 | Unsupported Media Type：客户所支持的数据类型，服务端无法满足。
  • 500 | Internal Server Error：服务器端的接口错误，此错误于客户端无关。

SDK

SDK表示工程对应用编排提供的API，SDK没有暴露REST接口。BO之间调用，只能使用SDK。