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

数据设计与抽象

Planning how your API will look begins earlier than you’d think; first you need to decide how your data will be designed and how your core service / application will work. If you’re doing API First Development this should be easy. If you’re attaching an API to an existing project, you may need to provide more abstraction.

Occasionally, a Collection can represent a database table, and a Resource can represent a row within that table. However, this is not the usual case. In fact, your API should abstract away as much of your data and business logic as possi