ASP.NET Core与RESTful API学习笔记 一、REST简介

ASP.NET Core与RESTful API学习笔记 一、REST简介

  • REST简介
    • API与REST
      • 什么是API?
      • 什么是REST?
      • REST约束
    • HTTP协议
      • 什么是HTTP?
      • 什么是HTTPS?
      • 统一资源定位符(URL)
      • 媒体类型
      • HTTP消息
      • HTTP方法
      • HTTP消息头
      • HTTP状态码
    • REST最佳实践

REST简介

REST(REpresentational State Transfer),表述性状态传递,是一种应用程序架构风格,用于构造简单、可靠、高性能的WEB应用程序。REST提出了一系列约束,遵循这些约束的应用程序称为RESTful API应用。

API与REST

什么是API?

  1. Application Programming Interface ,应用程序编程接口;
  2. API是一个系统向外暴露或公开的一套接口,外部应用程序通过API访问该系统;
  3. Web API与平台或编程语言无关;
  4. API通常是开发人员使用,设计良好,有丰富文档的Web API更易于被 开发人员接受并使用;

什么是REST?

  1. REpresentation State Transfer ,表述性状态传递;
  2. 是一种软件架构风格,用于构造简单、可靠、高性能的WEB应用程序;
  3. REST中,资源(Resource)是最基本的概念,任何能够命名的对象都是一个资源,每个资源都有一个统一的资源标识符URI(Uniform Resource Identifier),通过URI能够标识且访问该资源。因此,REST是一种基于资源的架构风格;
  4. 除了单个资源外,资源集合表示多个相同类型的资源,不同实体之间的关联关系能够由资源之间的层次关系体现出来(例如:某个客户的订单列表 user/1/orders),REST接口的端点(Endpoint)均以资源或资源集合结尾;
  5. 在REST中,对资源的操作通过HTTP方法来完成,例如:GET、POST、PUT、DELETE、HEAD、PATCH、OPTION等;

REST约束

REST定义了6个架构约束(Constraint),遵循这些约束的Web服务即REST风格的服务,如果违反其中任一约束,不能称期为RESTful。

  1. 客户端-服务端(Client-Server):关注点分离原则,客户端和服务端各自独立开发,且可认使用不同的技术或编程语言;
  2. 统一接口(Uniform Interface):是设计RESTful服力的基础,由4个子约束组成:
  • 资源标识,通过统一资源标识符(URL,Unoform Resource Locator)获取资源或对它执行操作;
  • 通过表述操作资源,当请求一个资源时,服务器返回该资源的一个表述,由表述正文和表述数据组成,格式通常为JSON、XML、HTML等;
  • 自描述信息,客户端与服务器之间传递的信息不仅包含资源的表述,也包含了资源表述的相关信息(如格式、长度等),甚至包含了资源相关的其他操作信息;
  • 超媒体作为应用程序状态引擎(HATEOAS),服务器返回的资源表述应包含与之相关的链接,这些链接能够对资源进行其他操作,比如当获取资源时,返回的链接中包含更新该资源、删除该资源等链接;
  1. 分层系统(Layered System):分层系统能够使用网络中介(如代理或网关等)透明地部署到客户端和服务器之间,中间服务器主要用于增强安全、负载均衡和响应缓存等目的;
  2. 缓存(Cache):客户端或网络中介均能够缓存服务器返回响应;
  3. 无状态(Stateless):服务器不会记录或存储客户端的状态信息,客户端请求服务时,必须在请求消息中包含所有与之相关的信息(如认证信息等);
  4. 按需编码(Code-On-Demand):允许服务器临时向客户端返回可执行的程序代码(如脚本等),用于为客户端提供扩展性或自定义功能。这一约束是可选的。

HTTP协议

什么是HTTP?

超文本传输协议(Hyper Text Transfer Protocol,HTTP),基于TCP/IP协议的应用层协议,采用了请求/响应模型,协议流程图如下

请求
响应
请求
响应
客户端Client
HTTP协议
服务器Server

其响应内容通常包括一个状态行和若干消息头,以及消息正文。

什么是HTTPS?

HTTP采用明文传输数据,超文本传输安全协议(Hyper Text Transfer Protocol Secure,HTTPS)采用密钥加密传输数据,也称为HTTP Over TLS、HTTP Over SSL。

统一资源定位符(URL)

URL代表网络上一个特定资源,是URI的子集,用于标识并定位资源。一个完整的URL形式如下:
< protocol>://< host>[:port] / [path] [?query] [#fragment]
示例:http://www.host.com/api/user?uid=1

  • http://,指定访问资源的网络协议,常见的还有https://、ftp://等;
  • www.host.com,指定主机名,DNS(Domain Name System)将主机名解析为一个具体的IP地址;
  • /api/user,这一部分是URL路径,指向主机上的具体资源;
  • [:port],端口号,可选,默认80;
  • ?uid=1,查询字符串,可选,URL中’?‘号后面的参数部分,采用’参数名’=‘参数值’的形式,多个参数与’&'号分隔;查询字符串由服务器上的Web应用程序决定如何处理;
  • [#fragment],锚部分,可选,URL中’#'号后面的内容,用于指明一个资源的特定位置,将定位到HTML页面中指定的元素;锚由客户端浏览器来处理。

媒体类型

HTTP服务器请求响应的资源内容类型(Content Type),称为媒体类型,也称为MIME类型(Multipurpose Internet Mail Extensions,多用途互联网邮件扩展类型),是一种表示文档的性质和格式的标准。MIME的组成结构:type/subtype,由类型和子类型两部分字符串组成,中间用’/'号分隔,并且不允许空格存在,MIME类型对大小写敏感。

MME类型 描述 示例
text 普通文本 text/plain、text/html、text/css、text/javascript
image 图片 image/gif、image/jpg、image/png、image/bmp、image/webp、
audio 音频 audio/midi、audio/mpeg、audio/webm、audio/ogg、audio/wav、
video 视频 video/webm、video/ogg
application 二进制数据 lapplication/xml、application/json、application/pdf、application/octet-stream、application/vnd.mspowerpoint、application/x-www-form-urlencoded

HTTP消息

HTTP消息是服务器与客户端之间交换数据的方式,分为请求消息和响应消息,都具有相似的结构,包括以下4部分的内容:

序号 名称 说明
1 起始行 第一行用于描述要执行的请求或者是对应的状态(成功或失败),起始行总是单行的
2 消息头 描述请求或响应的相关属性、配置、对消息正文的描述
3 空行 指明消息头已经发送完毕
4 消息正文 包含请求数据或响应资源的表述,这一部分可以为空

HTTP请求消息

//请求消息起始行包括HTTP方法(POST)、请求URL(/)、HTTP版本(HTTP/1.1)
POST / HTTP/1.1
Host: 127.0.0.1
Content-Type: application/x-www-form-urlencoded
Content-Length: length

inputParam=string

HTTP响应消息示例

//响应消息起始行称为状态行,包括HTTP版本(HTTP/1.1)、状态码(200)、状态文本(OK)
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length


string

HTTP方法

每个HTTP请求消息都必须包含一个HTTP方法,告诉服务器当前请求要执行哪一种操作。

方法名 作用 安全 幂等
GET 获取资源
POST 创建资源,请求的URI是资源集合
PUT 更新指定的资源,请求单个不存在的资源时可以创建资源
DELETE 删除指定的资源
PATCH 对资源进行部分更新
HEAD 与GET方法作用一样,但在响应消息中没有消息正文
OPTION 获取指定资源所支持的操作,服务器在返回的响应中会包含Allow消息头,它的值是HTTP方法列表,例如:Allow: GET, POST

“安全”,是指不会修改资源的方法。
“幂等”,是指多次对同一个URL调用同一个HTTP方法,其效果都是一样。

HTTP消息头

客户端与服务器之间的请求消息与响应消息均包含消息头,消息头由名称和值组成,中间用’:'冒号分隔,比如: Content-Type:text/html。

常见的请求消息头

消息头 说明 示例
Accept 告诉服务器,浏览器可以接受的响应内容类型 Accept: text/plain,text/html
Accept-Charaset 浏览器可以接受的字符编码集 Accept-Charaset:utf-8
Accept-Encoding 指定浏览器可以支持的web服务器返回内容压缩编码类型 Accept-Encoding:compress, gzip
Accept-Language 浏览器可接受的语言 Accept-Language:en,zh
Accept-Ranges 可以请求网页实体的一个或者多个子范围字段 Accept-Ranges: bytes
Authorization HTTP授权的授权证书 Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Cache-Control 指定请求和响应遵循的缓存机制 Cache-Control: no-cache
Connection 表示是否需要持久连接。(HTTP 1.1默认进行持久连接) Connection: close
Cookie HTTP请求发送时,会把保存在该请求域名下的所有cookie值一起发送给web服务器 Cookie: $Version=1; Skin=new;
Content-Length 请求的内容长度 Content-Length: 348
Content-Type 请求的与实体对应的MIME信息 Content-Type: application/x-www-form-urlencoded
Date 请求发送的日期和时间 Date: Tue, 15 Nov 2010 08:12:31 GMT
Expect 请求的特定的服务器行为 Expect: 100-continue
From 发出请求的用户的Email From: [email protected]
Host 指定请求的服务器的域名和端口号 Host: www.hostname.com
If-Match 只有请求内容与实体相匹配才有效 If-Match: “737060cd8c284d8af7ad3082f209582d”
If-Modified-Since 如果请求的部分在指定时间之后被修改则请求成功,未被修改则返回304代码 If-Modified-Since: Sat, 29 Oct 2010 19:43:31 GMT
If-None-Match 如果内容未改变返回304代码,参数为服务器先前发送的Etag,与服务器回应的Etag比较判断是否改变 If-None-Match: “737060cd8c284d8af7ad3082f209582d”
If-Range 如果实体未改变,服务器发送客户端丢失的部分,否则发送整个实体。参数也为Etag If-Range: “737060cd8c284d8af7ad3082f209582d”
If-Unmodified-Since 只在实体在指定时间之后未被修改才请求成功 If-Unmodified-Since: Sat, 29 Oct 2010 19:43:31 GMT
Max-Forwards 限制信息通过代理和网关传送的时间 Max-Forwards: 10
Pragma 用来包含实现特定的指令 Pragma: no-cache
Proxy-Authorization 连接到代理的授权证书 Proxy-Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Range 只请求实体的一部分,指定范围 Range: bytes=500-999
Referer 先前网页的地址,当前请求网页紧随其后,即来路 Referer: http://www.host.com/archives/71.html
TE 客户端愿意接受的传输编码,并通知服务器接受接受尾加头信息 TE: trailers,deflate;q=0.5
Upgrade 向服务器指定某种传输协议以便服务器进行转换(如果支持) Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
User-Agent User-Agent的内容包含发出请求的用户信息 User-Agent: Mozilla/5.0 (Linux; X11)
Via 通知中间网关或代理服务器地址,通信协议 Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1)
Warning 关于消息实体的警告信息 Warn: 199 Miscellaneous warning

常见的响应消息头

消息头 说明 示例
Accept-Ranges 表明服务器是否支持指定范围请求及哪种类型的分段请求 Accept-Ranges: bytes
Age 从原始服务器到代理缓存形成的估算时间(以秒计,非负) Age: 12
Allow 对某网络资源的有效的请求行为,不允许则返回405 Allow: GET, HEAD
Cache-Control 告诉所有的缓存机制是否可以缓存及哪种类型 Cache-Control: no-cache
Content-Encoding web服务器支持的返回内容压缩编码类型 Content-Encoding: gzip
Content-Language 响应体的语言 Content-Language: en,zh
Content-Length 响应体的长度 Content-Length: 348
Content-Location 请求资源可替代的备用的另一地址 Content-Location: /index.htm
Content-MD5 返回资源的MD5校验值 Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ==
Content-Range 在整个返回体中本部分的字节位置 Content-Range: bytes 21010-47021/47022
Content-Type 返回内容的MIME类型 Content-Type: text/html; charset=utf-8
Date 原始服务器消息发出的时间 Date: Tue, 15 Nov 2010 08:12:31 GMT
ETag 表示资源的当前状态的一个标识符 ETag: “737060cd8c284d8af7ad3082f209582d”
Expires 指定响应过期的日期和时间 Expires: Thu, 01 Dec 2010 16:00:00 GMT
Last-Modified 请求资源的最后修改时间 Last-Modified: Tue, 15 Nov 2010 12:45:26 GMT
Location 用来重定向接收方到非请求URL的位置来完成请求或标识新的资源 Location: https://localhost:5001/api/authors/1234
Pragma 包括实现特定的指令,它可应用到响应链上的任何接收方 Pragma: no-cache
Proxy-Authenticate 要求在访问代理时提供的身份认证信息 Proxy-Authenticate: Basic
refresh 应用于重定向或一个新的资源被创造,在5秒之后重定向(由网景提出,被大部分浏览器支持) Refresh: 5; url=http://localhost/manager/index.html
Retry-After 如果实体暂时不可取,通知客户端在指定时间之后再次尝试 Retry-After: 120
Server web服务器名称 Server: Apache/1.3.27 (Unix) (Red-Hat/Linux)
Set-Cookie 设置Http Cookie Set-Cookie: UserID=JohnDoe; Max-Age=3600; Version=1
Trailer 指出头域在分块传输编码的尾部存在 Trailer: Max-Forwards
Transfer-Encoding 文件传输编码 Transfer-Encoding:chunked
Vary 告诉下游代理是使用缓存响应还是从原始服务器请求 Vary: *
Via 告知代理客户端响应是通过哪里发送的 Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1)
Warning 警告实体可能存在的问题 Warning: 199 Miscellaneous warning
WWW-Authenticate 表明客户端请求使用的认证方式 WWW-Authenticate: Basic

自定义响应消息头的名称一般以"X-"开头。

HTTP状态码

HTTP状态码由三位十进制数字组成,第一位十进制数字定义了状态码的类型,后两位则表示在该类别中具体信息。HTTP状态码共分为5种类型:

状态码分类 状态码分类描述
1** 信息,服务器收到请求,需要请求者继续执行操作
2** 成功,服务器成功执行客户端所请求的操作
3** 重定向,需要进一步的操作以完成请求
4** 客户端错误,请求包含语法错误或请求内容不正确,无法完成请求
5** 服务器错误,服务器在处理请求的过程中发生了错误

常见HTTP状态码

状态码 状态码名称 状态码描述
100 Continue 客户端应当继续发送请求。这个临时响应是用来通知客户端它的部分请求已经被服务器接收,且仍未被拒绝。客户端应当继续发送请求的剩余部分,或者如果请求已经完成,忽略这个响应。服务器必须在请求完成后向客户端发送一个最终响应。
101 Switching Protocols 服务器已经理解了客户端的请求,并将通过Upgrade 消息头通知客户端采用不同的协议来完成这个请求。在发送完这个响应最后的空行后,服务器将会切换到在Upgrade 消息头中定义的那些协议。   只有在切换新的协议更有好处的时候才应该采取类似措施。例如,切换到新的HTTP 版本比旧版本更有优势,或者切换到一个实时且同步的协议以传送利用此类特性的资源。
102 Processing 由WebDAV(RFC 2518)扩展的状态码,代表处理将被继续执行。
200 OK 请求已成功,请求所希望的响应头或数据体将随此响应返回。
201 Created 请求已经被实现,而且有一个新的资源已经依据请求的需要而建立,且其 URI 已经随Location 头信息返回。假如需要的资源无法及时建立的话,应当返回 ‘202 Accepted’。
202 Accepted 服务器已接受请求,但尚未处理。正如它可能被拒绝一样,最终该请求可能会也可能不会被执行。在异步操作的场合下,没有比发送这个状态码更方便的做法了。   返回202状态码的响应的目的是允许服务器接受其他过程的请求(例如某个每天只执行一次的基于批处理的操作),而不必让客户端一直保持与服务器的连接直到批处理操作全部完成。在接受请求处理并返回202状态码的响应应当在返回的实体中包含一些指示处理当前状态的信息,以及指向处理状态监视器或状态预测的指针,以便用户能够估计操作是否已经完成。
203 Non-Authoritative Information 服务器已成功处理了请求,但返回的实体头部元信息不是在原始服务器上有效的确定集合,而是来自本地或者第三方的拷贝。当前的信息可能是原始版本的子集或者超集。例如,包含资源的元数据可能导致原始服务器知道元信息的超级。使用此状态码不是必须的,而且只有在响应不使用此状态码便会返回200 OK的情况下才是合适的。
204 No Content 服务器成功处理了请求,但不需要返回任何实体内容,并且希望返回更新了的元信息。响应可能通过实体头部的形式,返回新的或更新后的元信息。如果存在这些头部信息,则应当与所请求的变量相呼应。   如果客户端是浏览器的话,那么用户浏览器应保留发送了该请求的页面,而不产生任何文档视图上的变化,即使按照规范新的或更新后的元信息应当被应用到用户浏览器活动视图中的文档。   由于204响应被禁止包含任何消息体,因此它始终以消息头后的第一个空行结尾。
205 Reset Content 服务器成功处理了请求,且没有返回任何内容。但是与204响应不同,返回此状态码的响应要求请求者重置文档视图。该响应主要是被用于接受用户输入后,立即重置表单,以便用户能够轻松地开始另一次输入。   与204响应一样,该响应也被禁止包含任何消息体,且以消息头后的第一个空行结束。
206 Partial Content 服务器已经成功处理了部分 GET 请求。类似于 FlashGet 或者迅雷这类的 HTTP 下载工具都是使用此类响应实现断点续传或者将一个大文档分解为多个下载段同时下载。   该请求必须包含 Range 头信息来指示客户端希望得到的内容范围,并且可能包含 If-Range 来作为请求条件。   响应必须包含如下的头部域:   Content-Range 用以指示本次响应中返回的内容的范围;如果是 Content-Type 为 multipart/byteranges 的多段下载,则每一 multipart 段中都应包含 Content-Range 域用以指示本段的内容范围。假如响应中包含 Content-Length,那么它的数值必须匹配它返回的内容范围的真实字节数。   Date   ETag 和/或 Content-Location,假如同样的请求本应该返回200响应。   Expires, Cache-Control,和/或 Vary,假如其值可能与之前相同变量的其他响应对应的值不同的话。   假如本响应请求使用了 If-Range 强缓存验证,那么本次响应不应该包含其他实体头;假如本响应的请求使用了 If-Range 弱缓存验证,那么本次响应禁止包含其他实体头;这避免了缓存的实体内容和更新了的实体头信息之间的不一致。否则,本响应就应当包含所有本应该返回200响应中应当返回的所有实体头部域。   假如 ETag 或 Last-Modified 头部不能精确匹配的话,则客户端缓存应禁止将206响应返回的内容与之前任何缓存过的内容组合在一起。   任何不支持 Range 以及 Content-Range 头的缓存都禁止缓存206响应返回的内容。
207 Multi-Status 由WebDAV(RFC 2518)扩展的状态码,代表之后的消息体将是一个XML消息,并且可能依照之前子请求数量的不同,包含一系列独立的响应代码。
300 Multiple Choices 被请求的资源有一系列可供选择的回馈信息,每个都有自己特定的地址和浏览器驱动的商议信息。用户或浏览器能够自行选择一个首选的地址进行重定向。   除非这是一个 HEAD 请求,否则该响应应当包括一个资源特性及地址的列表的实体,以便用户或浏览器从中选择最合适的重定向地址。这个实体的格式由 Content-Type 定义的格式所决定。浏览器可能根据响应的格式以及浏览器自身能力,自动作出最合适的选择。当然,RFC 2616规范并没有规定这样的自动选择该如何进行。   如果服务器本身已经有了首选的回馈选择,那么在 Location 中应当指明这个回馈的 URI;浏览器可能会将这个 Location 值作为自动重定向的地址。此外,除非额外指定,否则这个响应也是可缓存的。
301 Moved Permanently 被请求的资源已永久移动到新位置,并且将来任何对此资源的引用都应该使用本响应返回的若干个 URI 之一。如果可能,拥有链接编辑功能的客户端应当自动把请求的地址修改为从服务器反馈回来的地址。除非额外指定,否则这个响应也是可缓存的。   新的永久性的 URI 应当在响应的 Location 域中返回。除非这是一个 HEAD 请求,否则响应的实体中应当包含指向新的 URI 的超链接及简短说明。   如果这不是一个 GET 或者 HEAD 请求,因此浏览器禁止自动进行重定向,除非得到用户的确认,因为请求的条件可能因此发生变化。   注意:对于某些使用 HTTP/1.0 协议的浏览器,当它们发送的 POST 请求得到了一个301响应的话,接下来的重定向请求将会变成 GET 方式。
302 Found 请求的资源现在临时从不同的 URI 响应请求。由于这样的重定向是临时的,客户端应当继续向原有地址发送以后的请求。只有在Cache-Control或Expires中进行了指定的情况下,这个响应才是可缓存的。   新的临时性的 URI 应当在响应的 Location 域中返回。除非这是一个 HEAD 请求,否则响应的实体中应当包含指向新的 URI 的超链接及简短说明。   如果这不是一个 GET 或者 HEAD 请求,那么浏览器禁止自动进行重定向,除非得到用户的确认,因为请求的条件可能因此发生变化。   注意:虽然RFC 1945和RFC 2068规范不允许客户端在重定向时改变请求的方法,但是很多现存的浏览器将302响应视作为303响应,并且使用 GET 方式访问在 Location 中规定的 URI,而无视原先请求的方法。状态码303和307被添加了进来,用以明确服务器期待客户端进行何种反应。
303 See Othe 对应当前请求的响应可以在另一个 URI 上被找到,而且客户端应当采用 GET 的方式访问那个资源。这个方法的存在主要是为了允许由脚本激活的POST请求输出重定向到一个新的资源。这个新的 URI 不是原始资源的替代引用。同时,303响应禁止被缓存。当然,第二个请求(重定向)可能被缓存。   新的 URI 应当在响应的 Location 域中返回。除非这是一个 HEAD 请求,否则响应的实体中应当包含指向新的 URI 的超链接及简短说明。   注意:许多 HTTP/1.1 版以前的 浏览器不能正确理解303状态。如果需要考虑与这些浏览器之间的互动,302状态码应该可以胜任,因为大多数的浏览器处理302响应时的方式恰恰就是上述规范要求客户端处理303响应时应当做的。
304 Not Modified 如果客户端发送了一个带条件的 GET 请求且该请求已被允许,而文档的内容(自上次访问以来或者根据请求的条件)并没有改变,则服务器应当返回这个状态码。304响应禁止包含消息体,因此始终以消息头后的第一个空行结尾。   该响应必须包含以下的头信息:   Date,除非这个服务器没有时钟。假如没有时钟的服务器也遵守这些规则,那么代理服务器以及客户端可以自行将 Date 字段添加到接收到的响应头中去(正如RFC 2068中规定的一样),缓存机制将会正常工作。   ETag 和/或 Content-Location,假如同样的请求本应返回200响应。   Expires, Cache-Control,和/或Vary,假如其值可能与之前相同变量的其他响应对应的值不同的话。   假如本响应请求使用了强缓存验证,那么本次响应不应该包含其他实体头;否则(例如,某个带条件的 GET 请求使用了弱缓存验证),本次响应禁止包含其他实体头;这避免了缓存了的实体内容和更新了的实体头信息之间的不一致。   假如某个304响应指明了当前某个实体没有缓存,那么缓存系统必须忽视这个响应,并且重复发送不包含限制条件的请求。   假如接收到一个要求更新某个缓存条目的304响应,那么缓存系统必须更新整个条目以反映所有在响应中被更新的字段的值。
305 Use Proxy 被请求的资源必须通过指定的代理才能被访问。Location 域中将给出指定的代理所在的 URI 信息,接收者需要重复发送一个单独的请求,通过这个代理才能访问相应资源。只有原始服务器才能建立305响应。   注意:RFC 2068中没有明确305响应是为了重定向一个单独的请求,而且只能被原始服务器建立。忽视这些限制可能导致严重的安全后果。
306 Unused 在最新版的规范中,306状态码已经不再被使用。
307 Temporary Redirect 请求的资源现在临时从不同的URI 响应请求。由于这样的重定向是临时的,客户端应当继续向原有地址发送以后的请求。只有在Cache-Control或Expires中进行了指定的情况下,这个响应才是可缓存的。   新的临时性的URI 应当在响应的 Location 域中返回。除非这是一个HEAD 请求,否则响应的实体中应当包含指向新的URI 的超链接及简短说明。因为部分浏览器不能识别307响应,因此需要添加上述必要信息以便用户能够理解并向新的 URI 发出访问请求。   如果这不是一个GET 或者 HEAD 请求,那么浏览器禁止自动进行重定向,除非得到用户的确认,因为请求的条件可能因此发生变化。
400 Bad Request 1、语义有误,当前请求无法被服务器理解。除非进行修改,否则客户端不应该重复提交这个请求。   2、请求参数有误。
401 Unauthorized 当前请求需要用户验证。该响应必须包含一个适用于被请求资源的 WWW-Authenticate 信息头用以询问用户信息。客户端可以重复提交一个包含恰当的 Authorization 头信息的请求。如果当前请求已经包含了 Authorization 证书,那么401响应代表着服务器验证已经拒绝了那些证书。如果401响应包含了与前一个响应相同的身份验证询问,且浏览器已经至少尝试了一次验证,那么浏览器应当向用户展示响应中包含的实体信息,因为这个实体信息中可能包含了相关诊断信息。参见RFC 2617。
402 Payment Required 该状态码是为了将来可能的需求而预留的。
403 Forbidden 服务器已经理解请求,但是拒绝执行它。与401响应不同的是,身份验证并不能提供任何帮助,而且这个请求也不应该被重复提交。如果这不是一个 HEAD 请求,而且服务器希望能够讲清楚为何请求不能被执行,那么就应该在实体内描述拒绝的原因。当然服务器也可以返回一个404响应,假如它不希望让客户端获得任何信息。
404 Not Found 请求失败,请求所希望得到的资源未被在服务器上发现。没有信息能够告诉用户这个状况到底是暂时的还是永久的。假如服务器知道情况的话,应当使用410状态码来告知旧资源因为某些内部的配置机制问题,已经永久的不可用,而且没有任何可以跳转的地址。404这个状态码被广泛应用于当服务器不想揭示到底为何请求被拒绝或者没有其他适合的响应可用的情况下。
405 Method Not Allowed 请求行中指定的请求方法不能被用于请求相应的资源。该响应必须返回一个Allow 头信息用以表示出当前资源能够接受的请求方法的列表。   鉴于 PUT,DELETE 方法会对服务器上的资源进行写操作,因而绝大部分的网页服务器都不支持或者在默认配置下不允许上述请求方法,对于此类请求均会返回405错误。
406 Not Acceptable 请求的资源的内容特性无法满足请求头中的条件,因而无法生成响应实体。   除非这是一个 HEAD 请求,否则该响应就应当返回一个包含可以让用户或者浏览器从中选择最合适的实体特性以及地址列表的实体。实体的格式由 Content-Type 头中定义的媒体类型决定。浏览器可以根据格式及自身能力自行作出最佳选择。但是,规范中并没有定义任何作出此类自动选择的标准。
407 Proxy Authentication Required 与401响应类似,只不过客户端必须在代理服务器上进行身份验证。代理服务器必须返回一个 Proxy-Authenticate 用以进行身份询问。客户端可以返回一个 Proxy-Authorization 信息头用以验证。参见RFC 2617。
408 Request Time-out 请求超时。客户端没有在服务器预备等待的时间内完成一个请求的发送。客户端可以随时再次提交这一请求而无需进行任何更改。
409 Conflict 由于和被请求的资源的当前状态之间存在冲突,请求无法完成。这个代码只允许用在这样的情况下才能被使用:用户被认为能够解决冲突,并且会重新提交新的请求。该响应应当包含足够的信息以便用户发现冲突的源头。   冲突通常发生于对 PUT 请求的处理中。例如,在采用版本检查的环境下,某次 PUT 提交的对特定资源的修改请求所附带的版本信息与之前的某个(第三方)请求向冲突,那么此时服务器就应该返回一个409错误,告知用户请求无法完成。此时,响应实体中很可能会包含两个冲突版本之间的差异比较,以便用户重新提交归并以后的新版本。
410 Gone 被请求的资源在服务器上已经不再可用,而且没有任何已知的转发地址。这样的状况应当被认为是永久性的。如果可能,拥有链接编辑功能的客户端应当在获得用户许可后删除所有指向这个地址的引用。如果服务器不知道或者无法确定这个状况是否是永久的,那么就应该使用404状态码。除非额外说明,否则这个响应是可缓存的。   410响应的目的主要是帮助网站管理员维护网站,通知用户该资源已经不再可用,并且服务器拥有者希望所有指向这个资源的远端连接也被删除。这类事件在限时、增值服务中很普遍。同样,410响应也被用于通知客户端在当前服务器站点上,原本属于某个个人的资源已经不再可用。当然,是否需要把所有永久不可用的资源标记为’410 Gone’,以及是否需要保持此标记多长时间,完全取决于服务器拥有者。
411 Length Required 服务器拒绝在没有定义 Content-Length 头的情况下接受请求。在添加了表明请求消息体长度的有效 Content-Length 头之后,客户端可以再次提交该请求。
412 Precondition Failed 服务器在验证在请求的头字段中给出先决条件时,没能满足其中的一个或多个。这个状态码允许客户端在获取资源时在请求的元信息(请求头字段数据)中设置先决条件,以此避免该请求方法被应用到其希望的内容以外的资源上。
413 Request Entity Too Large 服务器拒绝处理当前请求,因为该请求提交的实体数据大小超过了服务器愿意或者能够处理的范围。此种情况下,服务器可以关闭连接以免客户端继续发送此请求。   如果这个状况是临时的,服务器应当返回一个 Retry-After 的响应头,以告知客户端可以在多少时间以后重新尝试。
414 Request-URI Too Large 请求的URI 长度超过了服务器能够解释的长度,因此服务器拒绝对该请求提供服务。这比较少见,通常的情况包括:   本应使用POST方法的表单提交变成了GET方法,导致查询字符串(Query String)过长。   重定向URI “黑洞”,例如每次重定向把旧的 URI 作为新的 URI 的一部分,导致在若干次重定向后 URI 超长。   客户端正在尝试利用某些服务器中存在的安全漏洞攻击服务器。这类服务器使用固定长度的缓冲读取或操作请求的 URI,当 GET 后的参数超过某个数值后,可能会产生缓冲区溢出,导致任意代码被执行[1]。没有此类漏洞的服务器,应当返回414状态码。
415 Unsupported Media Type 对于当前请求的方法和所请求的资源,请求中提交的实体并不是服务器中所支持的格式,因此请求被拒绝。
416 Requested range not satisfiable 如果请求中包含了 Range 请求头,并且 Range 中指定的任何数据范围都与当前资源的可用范围不重合,同时请求中又没有定义 If-Range 请求头,那么服务器就应当返回416状态码。   假如 Range 使用的是字节范围,那么这种情况就是指请求指定的所有数据范围的首字节位置都超过了当前资源的长度。服务器也应当在返回416状态码的同时,包含一个 Content-Range 实体头,用以指明当前资源的长度。这个响应也被禁止使用 multipart/byteranges 作为其 Content-Type。
417 Expectation Failed 在请求头 Expect 中指定的预期内容无法被服务器满足,或者这个服务器是一个代理服务器,它有明显的证据证明在当前路由的下一个节点上,Expect 的内容无法被满足。
421 Misdirected Request 从当前客户端所在的IP地址到服务器的连接数超过了服务器许可的最大范围。通常,这里的IP地址指的是从服务器上看到的客户端地址(比如用户的网关或者代理服务器地址)。在这种情况下,连接数的计算可能涉及到不止一个终端用户。
422 Unprocessable Entity 从当前客户端所在的IP地址到服务器的连接数超过了服务器许可的最大范围。通常,这里的IP地址指的是从服务器上看到的客户端地址(比如用户的网关或者代理服务器地址)。在这种情况下,连接数的计算可能涉及到不止一个终端用户。
423 Locked 请求格式正确,但是由于含有语义错误,无法响应。(RFC 4918 WebDAV)423 Locked   当前资源被锁定。(RFC 4918 WebDAV)
424 Failed Dependency 由于之前的某个请求发生的错误,导致当前请求失败,例如 PROPPATCH。(RFC 4918 WebDAV)
425 Unordered Collection 在WebDav Advanced Collections 草案中定义,但是未出现在《WebDAV 顺序集协议》(RFC 3658)中。
426 Upgrade Required 客户端应当切换到TLS/1.0。(RFC 2817)
449 由微软扩展,代表请求应当在执行完适当的操作后进行重试。
500 Internal Server Error 服务器遇到了一个未曾预料的状况,导致了它无法完成对请求的处理。一般来说,这个问题都会在服务器的程序码出错时出现。
501 Not Implemented 服务器不支持当前请求所需要的某个功能。当服务器无法识别请求的方法,并且无法支持其对任何资源的请求。
502 Bad Gateway 作为网关或者代理工作的服务器尝试执行请求时,从上游服务器接收到无效的响应。
503 Service Unavailable 由于临时的服务器维护或者过载,服务器当前无法处理请求。这个状况是临时的,并且将在一段时间以后恢复。如果能够预计延迟时间,那么响应中可以包含一个 Retry-After 头用以标明这个延迟时间。如果没有给出这个 Retry-After 信息,那么客户端应当以处理500响应的方式处理它。   注意:503状态码的存在并不意味着服务器在过载的时候必须使用它。某些服务器只不过是希望拒绝客户端的连接。
504 Gateway Time-out 作为网关或者代理工作的服务器尝试执行请求时,未能及时从上游服务器(URI标识出的服务器,例如HTTP、FTP、LDAP)或者辅助服务器(例如DNS)收到响应。   注意:某些代理服务器在DNS查询超时时会返回400或者500错误
505 HTTP Version not supported 服务器不支持,或者拒绝支持在请求中使用的 HTTP 版本。这暗示着服务器不能或不愿使用与客户端相同的版本。响应中应当包含一个描述了为何版本不被支持以及服务器支持哪些协议的实体。
506 Variant Also Negotiates 由《透明内容协商协议》(RFC 2295)扩展,代表服务器存在内部配置错误:被请求的协商变元资源被配置为在透明内容协商中使用自己,因此在一个协商处理中不是一个合适的重点。
507 Insufficient Storage 服务器无法存储完成请求所必须的内容。这个状况被认为是临时的。WebDAV (RFC 4918)
509 Bandwidth Limit Exceeded 服务器达到带宽限制。这不是一个官方的状态码,但是仍被广泛使用。
510 Not Extended 获取资源所需要的策略并没有没满足。(RFC 2774)

REST最佳实践

1.使用名词的复数表示一个资源集合,如api.domain.com/users;
2.使用斜线 '/'表示资源之间的层次关系,如api.domain.com/users/1;
3.使用HTTP方法对资源增删改查,新增POST,DELETE删除,PUT修改,查询GET;
4.返回结果使用JSON;
5. 避免在 URI 中使用动词,如果一定要使用动词,则可使用‘-’作为URL路径的连接字符;如PUT /users/1/set-admin;
6.使用正确的状态码,同时仅在响应的 body 中返回错误信息,并设置正确的头部;
7.URI中不应该使用下划线,可使用‘-’代替下划线;
8.URL未尾不应包含斜线 ‘/’;
9.在响应中返回错误详情;
10.URI应使用小写字母;
11.不要嵌套资源,如GET: /authors/12/articles => GET: /articles/?author_id=12;
12.使用 querystring 来完成筛选和分页功能;

你可能感兴趣的:(ASP.NET,asp.net,restful)