你应该建立一个API，用于社区为基础的网站之前，开发商知道吗？ [英] What should a developer know before building an API for a community based website?
问题描述
应开发设计和实施一个API，用于社区为基础的网站知道开始重编码之前什么东西？有一堆的API有像 Twitter的API ，的 Facebook的API ， Flickr的API ，等等这些都是很好的例子。但是，你会怎么构建自己的API ？
What things should a developer designing and implementing an API for a community based website know before starting the heavy coding? There are a bunch of APIs out there like Twitter API, Facebook API, Flickr API, etc which are all good examples. But how would you build your own API?
你会使用什么样的技术？我认为这是使用 REST 式的接口，这样的API是从不同的平台访问一个好主意/客户端/浏览器/命令行工具（如卷曲）。我对吗？我知道，Web开发的所有原则应该像缓存，可用性，可扩展性，安全性，防止潜在的DOS攻击，验证等得到满足，当涉及到的API的一些最重要的事情是向后兼容性和文件。我缺少的东西吗？
What technologies would you use? I think it's a good idea to use REST-like interface so that the API is accessible from different platforms/clients/browsers/command line tools (like curl). Am I right? I know that all the principles of web development should be met like caching, availability, scalability, security, protection against potential DOS attacks, validation, etc. And when it comes to APIs some of the most important things are backward compatibility and documentation. Am I missing something?
在另一方面，从用户的角度思考（我的意思是谁去使用API的开发人员），你会在API中寻找什么？良好的文档？ code样本股？
On the other hand, thinking from user's point of view (I mean the developer who is going to use your API), what would you look for in an API? Good documentation? Lots of code samples?
对此问题予以的乔尔Coehoorn 问题<一个启发href=\"http://stackoverflow.com/questions/72394/what-should-a-developer-know-before-building-a-public-web-site\">\"What应开发人员构建公共网站之前，知道吗？。
这个问题是一个社会维基，所以我希望你能帮助我放在一个地方都应该为建设一个基于社区的网站的API时，要解决的事情。
This question is a community wiki, so I hope you will help me put in one place all the things that should be addressed when building an API for a community based website.
推荐答案
如果你真的要定义一个REST API，然后执行以下操作：
If you really want to define a REST api, then do the following:
-
忘了比其他所有技术问题的 HTTP和媒体类型
识别主要使用情况下，客户端将与API交互
Identify the major use cases where a client will interact with the API
编写客户端code执行那些用例对一个假想的HTTP服务器。在仅信息客户应该开始从一个GET请求到根API网址的响应。客户应确定媒体类型从HTTP Content-Type头的响应，它应该解析响应。这种反应应该包含链接，使客户端执行所有必需的操作API的其他资源。
Write client code that perform those "use cases" against a hypothetical HTTP server. The only information that client should start with is the response from a GET request to the root API url. The client should identify the media-type of the response from the HTTP content-type header and it should parse the response. That response should contain links to other resources that allow the client to perform all of the APIs required operations.
在创建一个REST API很容易把它作为用户界面一台机器，而不是使物体模型或过程模型。试想一下，机器通过检索响应，点击一个链接，处理响应和之后的下一个环节编程导航API。 客户端不应该构造基于它的服务器如何组织资源知识网址
When creating a REST api it is easier to think of it as a "user interface" for a machine rather than exposing an object model or process model. Imagine the machine navigating the api programmatically by retrieving a response, following a link, processing the response and following the next link. The client should never construct a URL based on its knowledge of how the server organizes resources.
如何这些链接的格式，并确定是至关重要的。你会在定义REST API让在最重要的决定是你的媒体类型的选择。你要么需要找到链接信息（
How those links are formatted and identified is critical. The most important decision you will make in defining a REST API is your choice of media types. You either need to find standard ways of representing that link information (think Atom, microformats, atom link-relations, Html5 link relations) or if you have specialized needs and you don't need really wide reach to many clients, then you could create your own media-types.
文件的媒体类型的结构以及它们可能包含的内容链接/链接关系。有关媒体类型的具体信息是在客户端的关键。有一个服务器返回的Content-Type：application / xml进行是没用的，客户如果想要做任何事情超过解析响应。客户端可以不知道什么是包含在类型application / XML的响应。有些人不相信你可以使用XML模式来定义这一点，但也有一些缺点这一点，它违反了REST自我描述性信息的约束。
Document how those media types are structured and what links/link-relations they may contain. Specific information about media types is critical to the client. Having a server return Content-Type:application/xml is useless to a client if it wants to do anything more than parse the response. The client cannot know what is contained in a response of type application/xml. Some people do believe you can use XML schema to define this but there are several disadvantages to this and it violates the REST "self-descriptive message" constraint.
记住什么URL看起来已经完全在客户应如何运作没有影响。唯一的例外是，一个媒体类型可以指定使用模板的URI和可限定的那些模板的参数。 URL的结构，当谈到选择一个服务器端框架成为显著。服务器控制URL结构，客户端不应该关心。但是，不要让服务器端框架决定了客户如何与API进行交互，并据此选择，要求你改变你的API框架非常谨慎。 HTTP应该是对客户端/服务器交互的唯一约束
Remember that what the URL looks like has absolutely no bearing on how the client should operate. The only exception to this, is that a media type may specify the use of templated URIs and may define parameters of those templates. The structure of the URL will become significant when it comes to choosing a server side framework. The server controls the URL structure, the client should not care. However, do not let the server side framework dictate how the client interacts with the API and be very cautious about choosing a framework that requires you to change your API. HTTP should be the only constraint regarding the client/server interaction.
这篇关于你应该建立一个API，用于社区为基础的网站之前，开发商知道吗？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
