最近一直在做公司的一个API平台的项目，前后大约有半年多了，中间穿插了好多其他的项目一起做的。上周经理要求写文档，我就重新打开项目开始检阅之前的代码，发现好多地方当初设计的并不合理，忽然就想到，一个好的API平台，应该怎么来设计呢？有哪些规范要遵守呢？面对自己的项目，感觉好多地方都要改，但是已经有人在用了，怎么办？全都要改动吗？所以就上网找解决方案，然后就发现一精品贴，现转载过来，以备不时查阅。
原文地址：，转载请注明，原文在这里，不是我的。
----------------------------
Principles of good RESTful API Design
好RESTful API的设计原则
Good API design is hard! An API represents a contract between you and those who Consume your data. Breaking this contract will result in many angry emails, and a slew of sad users with mobile apps which no longer work. Documentation is half the battle, and it is very difficult to find programmer who also likes to write.
Building an API is one of the most important things you can do to increase the value of your service. By having an API, your service / core application has the potential to become a platform from which other services grow. Look at the current huge tech companies: Facebook, Twitter, Google, GitHub, Amazon, Netflix… None of them would be nearly as big as they are today if they hadn’t opened up their data via API. In fact, an entire industry exists with the sole purpose of consuming data provided by said platforms.
The easier your API is to consume, the more people that will consume it.
The principles of this document, if followed closely when designing your API, will ensure that Consumers of your API will be able to understand what is going on, and should drastically reduce the number of confused and/or angry emails you receive. I’ve organized everything into topics, which don’t necessarily need to be read in order.
做出一个好的API设计很难。API表达的是你的数据和你的数据使用者之间的契约。打破这个契约将会招致很多愤怒的邮件，和一大堆伤心的用户-因为他们手机上的App不工作了。而文档化只能达到一半的效果，并且也很难找到一个愿意写文档的程序员。
你所能做的最重要一件事来提高服务的价值就是创建一个API。因为随着其他服务的成长，有这样一个API会使你的服务或者核心应用将有机会变成一个平台。环顾一下现有的这些大公司：Facebook，Twitter，Google， Github，Amazon，Netflix等。如果当时他们没有通过API来开放数据的话，也不可能成长到如今的规模。事实上，整个行业存在的唯一目的就是消费所谓平台上的数据。
你的API越容易使用，那么就会有越多的人去用它本文提到的这些原则，如果你的API能严格按照这些原则来设计，使用者就可以知道它接下来要做什么，并且能减少大量不必要的疑惑或者是愤怒的邮件。我已经把所有内容都整理到不同的主题里了，你无需按顺序去阅读它。
Definitions定义
Here’s a few of the important terms I will use throughout the course of this document:
Resource: A single instance of an object. For example, an animal.
Collection: A collection of homogeneous objects. For example, animals.
HTTP: A protocol for communicating over a network.
Consumer: A client computer application capable of making HTTP requests.
Third Party Developer: A developer not a part of your project but who wishes to consume your data.
Server: An HTTP server/application accessible from a Consumer over a network.
Endpoint: An API URL on a Server which represents either a Resource or an entire Collection.
Idempotent: Side-effect free, can happen multiple times without penalty.
URL Segment: A slash-separated piece of information in the URL.
这里有一些非常重要的术语，我将在本文里面一直用到它们：
资源：一个对象的单独实例，如一只动物
集合：一群同种对象，如动物
HTTP：跨网络的通信协议
客户端：可以创建HTTP请求的客户端应用程序
第三方开发者：这个开发者不属于你的项目但是有想使用你的数据
服务器：一个HTTP服务器或者应用程序，客户端可以跨网络访问它
端点：这个API在服务器上的URL用于表达一个资源或者一个集合
幂等：无边际效应，多次操作得到相同的结果
URL段：在URL里面已斜杠分隔的内容
Data Design and Abstraction
数据设计与抽象