- URI Format(RFC 3986)
- URI Rules
- Request Methods(RFC2616)
- Request Method Rules
- Response Status Codes
- Response Status Code Rules
- HTTP Headers Rules
- Media Types
- Registered Media Types
- Media Types Rules
- Message Body Rules
- Hypermedia Representation Rules
- Media Type Representation Rules
- Error Representation Rules
- Client Concerns Rules
- Final Thoughts Principles
URL = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]URI Rules
-
必须使用正斜杠分隔符(/)来表示层次结构关系
http://api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares
-
URI最后不应该有斜杠(/)
Incorrect: http://api.canvas.restapi.org/shapes/ Correct: http://api.canvas.restapi.org/shapes
-
应该使用连字符(-)来提高URI可读性
http://api.example.restapi.org/blogs/mark-masse/entries/this-is-my-first-post
-
URI中不应该使用下划线(_)
-
在URI路径中,应该首选小写字母
1: http://api.example.restapi.org/my-folder/my-doc Correct 2: HTTP://API.EXAMPLE.RESTAPI.ORG/my-fplder/my-doc Correct 3: httpL//api.example.restapi.org/My-Folder/my-doc Incorrect
-
文件扩展名不应该包含在URI中
Incorrect: http://api.college.restapi.org/students/3248234/transcripts/2005/fall.json Correct: http://api.college.restapi.org/students/3248234/transcripts/2005/fall
-
对于API,应该使用一致的子域名,API的完整域名应该添加一个名为api的子域
Incorrect: http://soccer.restapi.org Correct: http://api.soccer.restapi.org
-
对于客户端开发人员,应该使用一致的子域名
httpL//developer.soccer.restapi.org
-
表示文档资源的URI应该用单数名词
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/claudio
-
标识一个集合的URI应该用一个复数名词
http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players
-
标识资源存储的URI应该用复数名词
http://api.music.restapi.org/artists/mikemassedotcom/playlists
-
动词或动词短语应用于控制器名称
http://api.college.restapi.org/students/morgan/register http://api.example.restapi.org/lists/4324/dedupe http://api.ognom.restapi.org/dbs/reindex http://api.build.restapi.org/qa/nightly/runTestSuite
-
变量路径段可以用于基于标识的值进行替换
http://api.soccer.restapi.org/leagues/{leagueId}/teams/{teamsId}/players/{playerId} http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/21 -
CRUD函数名称不应该使用在URI中
Incorrect: GET /deleteUser?id=1234 GET /deleteUsers/1234 DELETE /deleteUser/1234 POST /users/1234/delete Correct: DELETE /users/1234
-
一个URI的查询组件可以用于过滤集合或存储
GET /users GET /users?role=admin
-
URI的查询组件应该用于分页收集或存储结果
GET /users?pageSize=25&&pageStartIndex=50
Request-Line = Method SP Request-URI SP HTTP-Version CRLF
GET is to retrieve a representation of a resource’s state.
HEAD is used to retrieve the metadata associated with the resource’s state.
PUT should be used to add a new resource to a store or update a resource.
DELETE removes a resource from its parent.
POST should be used to create a new resource within a collection and execute controllers.
Request Method Rules-
GET和POST不能用于其他请求方法
-
必须使用GET来检索资源的表达形式
$ curl -v http://api.example.restapi.org/greeting > GET /greeting HTTP/1.1 > User-Agent: curl/7.20.1 > Host: api.example.restapi.org > Accept: *.* < HTTP/1.1 200 OK < Date: Sat, 20 Aug 2011 16:02:40 GMT < Server: Apache < Expires: Sat, 20 Aug 2011 16:06:40 GMT < Cache-Control: max-age=60, must-revalidate < ETag: text/html:hello world < Last-Modified: Sat, 20 Aug 2011 16:02:17 GMT < Vary: Accept-Encoding < Content-Type: text/html
Greeting Hello World!


