我将为一个网络应用程序构建一个 API，并且我对人们可以建议的良好实践感兴趣。
我已经计划对其进行版本控制（版本 1 只能控制系统的某些方面，版本 2 可以控制更多，但这可能需要更改执行身份验证的方式，这与版本 1 不兼容），并且身份验证将不同于人们用来登录的标准用户名/密码（如果有人确实使用恶意工具，它不会让他们完全模仿，无论 API 允许什么）。
有没有人有进一步的想法，或者您使用过的具有特别好的 API 的网站示例？
I'm going to build an API for a web app and I'm interested in what people can suggest as good practices.
I'm already planning to make it versioned (version 1 can only control certain aspects of the system, version 2 could control more, but this may need a change in the way authentication is performed that would be incompatible with version 1), and the authentication will be distinct from the standard username/password people use to log in (if someone does use a malicious tool it won't open them up to full impersonation, just whatever the api allows).
Does anyone have further ideas, or examples of sites with particularly good APIs you have used?
发布评论
评论（5）
使用休息。
阅读 API 标准，或者复制流行标准之一的想法。
验证用户身份时要小心。
开始非常非常简单。
构建一个使用您的 API（即使它没有用）的网站来检查一切是否正常。 也许您可以构建网站的移动版本或迫使您深入使用 API 的东西。
Use REST.
Read up on standards for APIs, or copy the ideas from one of the popular ones.
Be careful when authenticating users.
Start very very simple.
Build a site that uses your API (even if it's not useful) to check things work. Perhaps you could build a mobile version of the site or something that forces you to use the API in a lot of depth.
我会看一下经过验证的 API：
关于这些 API 是否“好”有很多争论，但我认为它们的成功已经得到证明，而且它们都是便于使用。
I would take a look at proven APIs:
There's a lot of argument about whether these APIs are "good" but I think their success is demonstrated, and they're all easy to use.
使用休息。
RESTful Web 服务架构易于实现，并利用 HTTP 的优势和语义来实现其预期目的。 它是面向资源的，就像网络本身一样。
Amazon Web Services、Google 和许多其他公司提供 REST API 来与其产品交互。
Use REST.
RESTful web services architecture is easy to implement and uses the strengths and semantics of HTTP for what they were intended. It's resource-oriented, just like the web itself.
Amazon Web Services, Google and many others offer REST APIs to interact with their products.
阅读RESTful Web Services一书，它可以让您很好地了解如何在实践中使用 REST，并快速上手，充满信心地立即开始。 这比仅仅查看现有 API 更有用，因为它还讨论了设计选择和权衡。
Read the RESTful Web Services book, which give you a good overview of how to use REST in practice, and get to up to speed quickly enough to get started now, with some confidence. This is more useful than just looking at an existing API, because it also discusses design choices and trade-offs.
1) 将版本号直接烘焙到 URL 中，而不是将其作为参数传递，因为这样您就可以完全自由地在每次版本更新时更改 API 命名空间的组织。
2) 使您的 URL 重写规则（如果有）尽可能简单/精简（但不能更简单），同时使您的 URL 尽可能美观（但仅此而已）。
3) 始终为每个响应寻找可以找到的最佳 HTTP 状态代码（例如，不要忘记 202 和 207）。
4) 实施法西斯参数验证逻辑和信息错误消息。
5) 在适当的情况下使用 HTTP 请求标头而不是参数（例如 Accept，以允许客户端指定所需的响应数据格式）。
6) 以这样的方式组织你的“名词”，使不同客户端受众使用的 URL 在 URL 树的“根”附近分开（这使得在需要时更容易为这些不同的受众实施不同的身份验证机制，甚至映射URL 树的不同部分到不同的服务器）。
7) 如果您在与 API 相同的域中提供常规网页并使用相同的身份验证凭据，则需要在 API 请求中包含 X-Requested-With 标头，以避免 XSRF 漏洞。
1) Bake the version number directly into the URL rather than passing it as a parameter, since that gives you complete freedom to change the organization of your API namespace with each version bump.
2) Keep your URL rewriting rules (if any) as simple/lean as possible (but no simpler), while making your URLs as beautiful as possible (but no more).
3) Always look for the best HTTP status code you can find for each response (and don't forget about 202 and 207, for example).
4) Implement fascist parameter validation logic, and informative error messages.
5) Use HTTP request headers where appropriate instead of parameters (like Accept, for example, to allow clients to specify the desired data format of the response).
6) Organize your "nouns" in such a way that the URLs used by different client audiences are separated near the "root" of your URL tree (this makes it easier to enforce different authentication mechanisms for those different audiences if needed, or even map different portions of your URL tree to different servers).
7) If you're serving regular web pages off the same domain as your APIs and use the same authentication credentials, require an X-Requested-With header in your API requests so as to avoid XSRF vulnerabiities.