本文目录
- API 设计规范
- Microservices中的API设计 - Problem + json处理错误
- API设计都有哪些缺陷
- http的api接口需要设计哪些东西
- 如何设计API接口，请求接口时需要进行身份验证，防止第三方随意调用接口
API 设计规范
设计时通过将请求和响应之间的不同部分隔离来让事情变得简单。保持简单的规则让我们能更关注在一些更大的更困难的问题上。
请求和响应将解决一个特定的资源或集合。使用路径（path）来表明身份，body来传输内容（content）还有头信息（header）来传递元数据（metadata）。查询参数同样可以用来传递头信息的内容，但头信息是首选，因为他们更灵活、更能传达不同的信息。
所有的访问API行为，都需要用TLS通过安全连接来访问。没有必要搞清或解释什么情况需要TLS 什么情况不需要TLS，直接强制任何访问都要通过 TLS。
***隐藏网址***
把非TLS的请求重定向(Redirect)至TLS连接是不明智的，这种含混/不好的客户端行为不会带来明显好处。依赖于重定向的客户端访问不仅会导致双倍的服务器负载，还会使 TLS 加密失去意义，因为在首次非TLS调用时，敏感信息就已经暴露出去了。
制定版本并在版本之间平缓过渡对于设计和维护一套API是个巨大的挑战。所以，最好在设计之初就使用一些方法来预防可能会遇到的问题。
为了避免API的变动导致用户使用中产生意外结果或调用失败，最好强制要求所有访问都需要指定版本号。请避免提供默认版本号，一旦提供，日后想要修改它会相当困难。
最适合放置版本号的位置是头信息(HTTP Headers)，在 Accept 段中使用自定义类型(contenttype)与其他元数据(metadata)一起提交。例如:
在所有返回的响应中包含ETag头信息，用来标识资源的版本。这让用户对资源进行缓存处理成为可能，在后续的访问请求中把If-None-Match头信息设置为之前得到的ETag值，就可以侦测到已缓存的资源是否需要更新。
为每一个请求响应包含一个Request-Id头，并使用UUID作为该值。通过在客户端、服务器或任何支持服务上记录该值，它能为我们提供一种机制来跟踪、诊断和调试请求。
一个大的响应应该通过多个请求使用Range头信息来拆分，并指定如何取得。详细的请求和响应的头信息（header），状态码(status code)，范围(limit)，排序(ordering)和迭代(iteration)等，参考 Heroku PlatformAPI discussion of Ranges .
在 PUT/PATCH/POST 请求的正文（request bodies）中使用JSON格式数据，而不是使用form 表单形式的数据。这与我们使用JSON格式返回请求相对应，例如:
资源名 （Resource names）:使用复数形式为资源命名，除非这个资源在系统中是单例的 (例如，在大多数系统中，给定的用户帐户只有一个)。 这种方式保持了特定资源的统一性。
行为 （Actions）:好的末尾不需要为资源指定特殊的行为，但在特殊情况下，为某些资源指定行为却是必要的。为了描述清楚，在行为前加上一个标准的actions：
例如：
为了和域名命名规则保持一致，使用小写字母并用 - 分割路径名字，例如:
属性也使用小写字母，但是属性名要用下划线 _ 分割，以便在Javascript****中省略引号。例如：
在某些情况下，让用户提供ID去定位资源是不方便的。例如，一个用户想取得他在Heroku平台app信息，但是这个app的唯一标识是UUID。这种情况下，你应该支持接口通过名字和ID都能访问，例如:
不要只接受使用名字而放弃了使用id。
在一些有父路径/子路径嵌套关系的资源数据模块中，路径可能有非常深的嵌套关系，例如:
推荐在根(root)路径下指定资源来限制路径的嵌套深度。使用嵌套指定范围的资源。在上述例子中，dyno属于app，app属于org可以表示为：
为每一次的响应返回合适的HTTP状态码。好的响应应该使用如下的状态码:
200: GET请求成功，及DELETE或PATCH同步请求完成，或者PUT同步更新一个已存在的资源;
201: POST同步请求完成，或者PUT同步创建一个新的资源;
202: POST，PUT，DELETE，或PATCH请求接收，将被异步处理;
206: GET 请求成功，但是只返回一部分;
使用身份认证（authentication）和授权（authorization）错误码时需要注意：
401 Unauthorized: 用户未认证，请求失败;
403 Forbidden: 用户无权限访问该资源，请求失败;
当用户请求错误时，提供合适的状态码可以提供额外的信息：
422 Unprocessable Entity: 请求被服务器正确解析，但是包含无效字段;
429 Too Many Requests: 因为访问频繁，你已经被限制访问，稍后重试;
500 Internal Server Error: 服务器错误，确认状态并报告问题.
对于用户错误和服务器错误情况状态码，参考： ** **HTTP response code spec
提供全部可显现的资源表述 (例如：这个对象的所有属性) ，当响应码为200或是201时返回所有可用资源，包含 PUT/PATCH和 DELETE 请求，例如:
当请求状态码为202时，不返回所有可用资源，例如：
在默认情况给每一个资源一个id属性。除非有更好的理由，否则请使用UUID。不要使用那种在服务器上或是资源中不是全局唯一的标识，尤其是自动增长的id。
生成小写的UUID格式 8-4-4-4-12，例如：
为资源提供默认的创建时间 created_at 和更新时间 updated_at，例如:
有些资源不需要使用时间戳那么就忽略这两个字段。
仅接受和返回UTC格式的时间。ISO8601格式的数据，例如:
使用嵌套对象序列化外键关联，例如:
而不是像这样:
这种方式尽可能的把相关联的资源信息内联在一起，而不用改变资源的结构，或者引入更多的顶层字段，例如:
响应错误的时，生成统一的、结构化的错误信息。包含一个机器可读的错误 id，一个人类可读的错误信息（message），根据情况可以添加一个url来告诉客户端关于这个错误的更多信息以及如何去解决它，例如:
文档化错误信息格式，以及客户端可能遇到的错误信息id。
客户端的访问速度限制可以维护服务器的良好状态，保证为其他客户端请求提供高性的服务。你可以使用 token bucket algorithm 技术量化请求限制。
为每一个带有RateLimit-Remaining响应头的请求，返回预留的请求tokens。
请求中多余的空格会增加响应大小，而且现在很多的HTTP客户端都会自己输出可读格式（"prettify"）的JSON。所以最好保证响应JSON最小化，例如：
而不是这样：
你可以提供可选的方式为客户端提供更详细可读的响应，使用查询参数（例如：?pretty=true）或者通过Accept头信息参数（例如：Accept:application/vnd.heroku+json;version=3; indent=4;）。
提供一个机器可读的模式来恰当的表现你的API。使用 prmd 管理你的模式，并且确保用prmd verify验证是有效的。
提供人类可读的文档让客户端开发人员可以理解你的API。
如果你用prmd创建了一个概要并且按上述要求描述，你可以为所有节点很容易的使用prmd doc生成Markdown文档。
除了节点信息，提供一个API概述信息:
提供可执行的示例让用户可以直接在终端里面看到API的调用情况，最大程度的让这些示例可以简单的使用，以减少用户尝试使用API的工作量。例如:
如果你使用 prmd 生成Markdown文档，每个节点都会自动获取一些示例。
描述您的API的稳定性或是它在各种各样节点环境中的完备性和稳定性，例如：加上原型版（prototype）/开发版（development）/产品版（production）等标记。
更多关于可能的稳定性和改变管理的方式，查看 ** **Heroku API compatibility policy
一旦你的API宣布产品正式版本及稳定版本时，不要在当前API版本中做一些不兼容的改变。如果你需要，请创建一个新的版本的API。
Microservices中的API设计 - Problem + json处理错误
在 Mircroservices API 设计中,为了让错误信息更具有描述性，我们采用 Problem+json 的方式输出错误。 采用Http Status Codes + Empty Response来返回错误数据: 采用 problem+json 格式我们可以让错误输出更具有描述性，可以让 API Consumer 更好进行错误处理 例如采用如下信息描述订单问题:
API设计都有哪些缺陷
关于API的开发设计相信大多数的程序员应该都掌握了不少方法了，今天我们就通过案例分析来简单了解一下，关于API设计都有哪些常见的问题。
当我们谈论到“REST”，可以讲的通俗一点它就是一种基于HTTP形式的API。事实上，大量含有URI的“REST”形式的API都有提供CRUD操作，有些URI是在负载的时候就嵌入的，所以可以说RESTful是一开始就有的。但是现在我偶尔还会听到“CRUDL”这个名词，这个“L”代表List。
当我在AWS工作时，我们常做的事是设计一个服务或者一款APP的数据层和它的控制层。举例，假定数据库像RDS服务一样。那么在app的控制层中你去创建，配置，备份，启动，停止和删除数据库。数据层主要内容是SQL语句，连接池和RDBMS包
非常有趣的是我们需要去注意的一点是控制层可以非常好的匹配RESTFUl风格的API，但是数据层就不是这样了。在数据库当中REST并非属于必要，(但是DynamoDB数据库的数据层是非常嵌合RESTFUL)。
我在想模式能否是这样，当你在控制层去删除和创建对象时，控制层可以很好嵌合大多数RESTFUL风格的API。数据层却完全不一样。要不是因为REST和控制层像是天造地设一样合适，我还以为不论什么想要替换掉REST都将从数据层开始。
REST-ful缺陷我们想超越REST的原因可能有哪些?下面我列出了一些：
延迟
创建和销毁一个HTTP连接的每一个操作都不是没有代价的。虽然为了减小这种代价努力了几十年，但是它依然存在。
比如说两个我身边的朋友创建的消息服务的例子：AmazonSQS和MQ.SQS已经运行了十多年，每秒处理百万级的消息，而且如果你的消息发送者和接收者能合理平衡的话，可以做到出奇的快。甚至我听说过消息还没有发送就已经被接受的例子。其实是长轮询的接收者在发送端销毁PutMessage的HTTP连接之前就已经收到消息。回龙观电脑培训认为一方面，它没有使用HTTP，而是用了TCP/IP长连接和它自己的报文协议。所以可以得到惊讶的发送和接收延迟。但是另一方面，你的消息吞吐量受限于关闭这些连接的“messagebroker”所能处理的连接数。很多选择MQ的人的原因相信他们这么做的因为是不想用RESTful接口。
http的api接口需要设计哪些东西
***隐藏网址***
但以后也不排除还会出现比如websocket等协议，甚至很多内部使用的协议都是开发自己定义的，并没有名字
如何设计API接口，请求接口时需要进行身份验证，防止第三方随意调用接口
1. 设定一个密钥比如key = ‘2323dsfadfewrasa3434’。 2. 这个key 只有发送方和接收方知道。3. 调用时，发送方，组合各个参数用密钥 key按照一定的规则(各种排序，MD5，ip等)生成一个access_key。一起post提交到API接口。4. 接收方拿到post过来的参数以及这个access_key。也和发送一样，用密钥key 对各个参数进行一样的规则(各种排序，MD5，ip等)也生成一个access_key2。5. 对比access_key 和access_key2 。一样。则允许操作，不一样，报错返回或者加入黑名单。
