rest api_REST API-白红宇

rest api_REST API

阅读量：2523 次

发布时间：2019-05-11

本文共 5411 字，大约阅读时间需要 18 分钟。

rest api

历史 (History)

REST stands for Representational State Transfer protocol. Roy Fielding defined REST in his PhD dissertation in 2000.

REST代表再表象小号泰特贸易交接协议。 Roy Fielding在2000年的博士学位论文中定义了REST。

什么是REST API？ (What is a REST API?)

REST was developed to provide a uniform interface for

REST的开发旨在为

Identifying resources
识别资源

Manipulation of resources
资源操纵

Self descriptive messages
自我描述性信息

Using Hypermedia as the Engine of Application State (HATEOS)
使用超媒体作为应用程序状态(HATEOS)的引擎

最佳实践 (Best Practices)

基本 (Basics)

Method || ||

方法 || ||

GET || List all the cars || Retrieve an individual car
GET || 列出所有汽车|| 取回一辆车

POST || Create a new car || Error
POST || 创建新车|| 错误

PUT || Replace cars collections || Replace the car with id 1234
放入|| 替换汽车收藏|| 更换ID为1234的汽车

with new one
与新的

DELETE || Delete all cars || Delete car with id 1234
删除|| 删除所有汽车|| 删除ID为1234的汽车

Note while PUT operations either client or server can generate id’s

请注意，无论是客户端还是服务器，PUT操作都可以生成ID

名词好，动词不好 (Nouns are good Verbs are bad)

Use nouns to refer resources like cars, fruits etc.
使用名词来指代诸如cars ， fruits等资源。

Use verbs for action declarations convertMilesToKms, getNutritionalValues
使用动词进行动作声明convertMilesToKms ， getNutritionalValues

单数还是复数？ (Singular or Plural?)

Use correct grammar for declaration

使用正确的语法进行声明

Avoid /person/145

避免 /person/145

Prefer /people/154 Assume to return 154th person from list of people

首选 /people/154假定从人列表中返回第154人

用例 (Use cases)

Use anyone of the below patterns and be consistent!

请使用以下任何一种模式并保持一致！

Case StylesExampleUpperCamelCasehttp://api.fintech.cp/DailyTransactions/TodaylowerCamelCasehttp://api.fintech.cp/dailyTransactions/todaysnake_casehttp://api.fintech.cp/daily_transactions/today

案例StylesExample UpperCamelCase http://api.fintech.cp/DailyTransactions/Today lowerCamelCase http://api.fintech.cp/dailyTransactions/today snake_case http://api.fintech.cp/daily_transactions/today

关系和资源 (Relationships and Resources)

Resources can have one-to-many, many-to-many, many-to-one relationships etc. Mapping them correctly is crucial.
资源可以具有one-to-many ， many-to-many ， many-to-one关系等。正确地映射它们至关重要。

One-to-Many Mapping

一对多映射

For example, Tickets/145/messages/4 suggests one-to-many relationship between tickets and messages. Meaning 1 ticket has N messages. Message isn’t standalone resource. You can’t have /messages/4.

例如， Tickets/145/messages/4建议tickets和messages之间的一对多关系。含义1张票有N消息。消息不是独立资源。您不能有/messages/4 。

Many to Many Mapping

多对多映射

For example, /usergroups/345/users/56 suggests select 345th user group and get user with id 56. However, one user might be in multiple usergroups i.e. /usergroups/209/users/56 is also valid. In such case so for seperating the depedant resource users into a seperate endpoint like /users/56 and provide resource linking in /usergroups/209/users/56

例如， /usergroups/345/users/56建议选择第345个用户组并获取ID为56的用户。但是，一个用户可能在多个usergroups即/usergroups/209/users/56也有效。在这种情况下，为了将消耗资源的users分离到一个单独的端点(如/users/56并在/usergroups/209/users/56提供资源链接

API参数 (API Parameters)

PATH : required to access the resource E.g. /cars, /fruits
PATH： 需要访问资源如/cars ， /fruits

Query Parameters : optional filter the list E.g. /cars?type=SUV&year=2010
查询参数 ：可选过滤列表，例如/cars?type=SUV&year=2010

Body : Resource specific logic. Advance search query. Sometimes it might have both Query and body.
正文：特定于资源的逻辑。提前搜索查询。有时它可能同时具有查询和正文。

Header : Should contain global or platform wide data. E.g. API key parameters, encrypted keys for auth, device type information e.g. mobile or desktop or endpoint, device data type e.g. xml or json. Use header to communicate these parameters
标头：应包含全局或平台范围的数据。例如API密钥参数，用于auth的加密密钥，设备类型信息(例如移动或桌面或端点)，设备数据类型(例如xml或json)。使用标头传达这些参数

HTTP状态码 (HTTP Status Codes)

Use correct status codes

使用正确的状态码

CodesMeaning1xxRequest received and understood.2xxAction requested by client was received, understood and requested.3xxClient must take additional action to complete the request. Most of these status codes are used in URL Redirection.4xxIntended for situations where it seems the error was caused by the client.5xxThe server failed to fulfil a request.

CodesMeaning1xxRequest已接收并被理解。2xx客户端所请求的操作已被接收，理解并被请求。3xxClient必须采取其他操作来完成请求。这些状态代码大多数用于URL重定向。4xx用于似乎错误是由客户端引起的情况。5xx服务器无法满足请求。

Little more on 2xx!

2xx上的更多内容！

201 Resource Created. POST /cars should return HTTP 201 created with location header stating how to access the resource E.g. location : api.com/cars/124 in header
201资源已创建。 POST /cars应该返回与创建HTTP 201 location头，说明如何访问资源如location ： api.com/cars/124在头

202 - Accepted

202-已接受

Use this if the task is huge to run. Tell the client, it has accepted the request and will/is process/processing No payload is returned

如果任务要运行，请使用此选项。告诉客户，它已经接受了请求并且将/正在处理/正在处理没有返回有效载荷

204 - No content

204-无内容

Used when deleted DELETE cars/124 Returns no content. But can also return 200 OK if API intends to send the deleted resource for further processing.

删除后使用DELETE cars/124返回任何内容。但是，如果API打算发送已删除的资源进行进一步处理，也可以返回200 OK 。

The dangerous 5xx resources!

危险的5xx资源！