优异的API规划论题，在许多团队呈现，这些团队正在尽力完善他们的API战略。

在之前发布的博客上，我扼要的评论了API规划的重要性。一个规划杰出的API应该包括那些优点：你的API应该能进步开发者经历、便利的方便文档和高可用性。

但优异的API规划终究应该怎么做?在这个博客中，我将具体的介绍一些RESTful API的***规划。

一个规划杰出的API的特色

一般来说，一个有用的API规划遇有以下特色：

• 易于阅览和运用。一个规划杰出的API应该很简略被运用，其资源和相关操作可以快速的被运用它的开发人员回忆。
• 难以误用。规划杰出的API完成和集成将是个简略的进程，写出过错代码将变得不太或许。没有严厉依照API开发攻略的终端用户将会得到详实的信息反应。
• 完好又简练. ***，一个完好的API应该具有老练的运用避免你的数据被走漏。API完好性会跟着时刻的推移而改动，大多数的API规划人员和开发人员都应在现有根底上逐渐构建新的API。这是每一个运用API的工程师或公司都有必要坚持的理念。

为阐明下面列出的概念， 我会以一个相片同享的运用程序举例。 该运用程序答运用户上传相片， 以拍照地址和心境标签描绘相片特征。

调集，资源及其网址

了解资源和调集

资源是REST概念的根底。 一条资源是一个重要目标，它本身可以被引证。 一条资源含有数据，与其他资源的联系，以及操作办法，以答应拜访和处理相关信息。

一组资源被称为一个调集。 调集和资源的内容取决于你的安排和顾客的需求。 例如，假如你以为，商场取得了你的产品用户群的根本信息会获益， 那么，你就可以将此作为调集或资源。

共同资源定位器(URL)确认了资源的在线方位。 URL指向你API资源存在的方位。 基URL是这个方位的共同部分。

在相片同享运用一例中， 咱们可以揭露用户数据，只需用户经过调集和资源运用该运用程序， 经由恰当的URL拜访。

1. /users：用户的调集。
2. /users/username1：一个特定用户的信息资源。

名词化的URL更好

URL应该是整齐、高雅和简略的，这样开发人员更易在他们的web程序中运用你的产品。 很长且难以了解的URL不只看起来很糟糕，而且在记载时简略呈现过错。所以运用名词应该是很好的。

没有规则让资源名词运用奇数或复数，可是在假如是调集的话运用复数无疑很好的。 具有类似的资源和调集别离坚持它们的共同性是较好的做法。

坚持这些名词的自解释性，有助于开发人员了解从URL描绘的资源, 这终究会使他们运用你的API。

回到相片同享运用程序，它具有回来调集的公共API /users 、/photos。留意到它们都是复数名词了吗? 它们也是自描绘的，咱们可以推断出 /users 和/photos别离是获取产品注册的用户信息和同享的相片。

用HTTP办法来描绘资源的功用

一切资源都有一组办法，可以对它们进行操作由该接口露出的数据。

REStful APIs包括首要的HTTP办法，其杰出的界说和独立的功用可以应对一切资源。这儿是RESTful API里常用HTTP办法列表，这些办法界说CRUD怎么操作资源和调集。

(假如你想了解PUT和PATCH的不同，可以到StackOverflow上看看这个)

虽然在URL中运用动词也不错，可是GET, PUT, POST, DELETE操作现已用于描绘了资源的操作，因此在URL中运用动词替代名词会显得比较紊乱。

在相片同享app中，/users 和/photos 是一个端点，API的终端顾客可以更直观的运用RESTful CRUD 进行上述的操作。

呼应

供给反应,以协助开发人员成功

在他们运用你的产品时向开发人员供给杰出的反应，关于提高运用率和用户坚持率是很好的。每一个客户端的恳求和服务端的呼应都可以看做是一个音讯，在理想化的RESTful 生态系统中，这些音讯有必要是自描绘的。

杰出的反应关于完成的验证是活跃的，过错完成发生的音讯可以协助用户调试和纠正运用产品的不正确办法。关于API, 过错信息是运用API上下文的杰出办法之一。

调整你的过错与规范HTTP代码共同。客户端引发的过错应该运用400类型过错，假如是服务端的过错应该运用500类型来呼应。 一个对资源操作成功后应该回来一个200类型的呼应。

有许多的呼应代码。想了解更多, 看看这个REST API教程.

一般来说，运用你的API时有三种或许就成果：

客户端运用程序的行为是过错的(客户端过错–4xx呼应代码)

API行为过错 (服务器过错- 5 xx呼应代码)

客户端和API作业正常 (成功– 2xx呼应代码)

成功处理客户运用你的API时遇到的问题将大大改进开发人员运用体会和避免乱用API。 具体描绘这些过错，一起坚持简明和整齐。在过错音讯中供给满足的信息有助于用户处理它们的问题，假如你觉得需求愈加具体的信息，***另写文档并在此处供给链接。

GET 呼应比如

一个杰出规划的API应该有呼应示例，以了解是否成功调用了一个URL。呼应示例应该简略、简练和易于了解的。 一个好的经历法则是：协助开发人员在5秒内了解一个成功的呼应。回到咱们的相片同享运用，咱们界说了 /users 和 /photos URL。 /users 应该易数组的办法供给一切注册的用户，而且包括用户称号和参加日期特点。

你可以在Swagger(OpenAPI)中运用 API规划东西来界说你的API，详述如下：

responses:
200:
description:Successfullyreturnedinformationaboutusers
schema:
type:array
items:
type:object
properties:
username:
type:"string"
example:"kesh92"
created_time:
type:"dateTime"
example:"2010-01-12T05:23:19+0000"

留意数据类型和实例的每个呼应项注释，终究用户希望的是一个成功的GET调用。成功呼应后终究用户将接纳的JSON看起来如下：

{
“data”:[
{
“Username”:“example_user1”,
“created_time":“2013-12-23T05:51:14+0000”
},
{
“username”:“example_user2”,
“created_time":“2015-3-19T17:51:15+0000”
}
….
]
}

假如用户调用了这个办法，就应该取得包括上述数据和一个阐明正确调用了的200呼应状况码。 相同的,，一个不正确的调用应该发生恰当的400 或500 呼应状况码和其它相关信息，以协助用户更好地操作。

恳求

高雅的处理复杂性

你企图敞开的数据包括很多的有利于用户的特点，这些特点描绘的根本资源和阻隔特定信息，可以经过恰当的办法来操作。

一个API应该尽力供给完好的信息、数据和资源来协助开发者以无缝的办法与之整合。

但是， 完好意味着对你的API考虑通用运用状况。或许会有许多这样的联系和特点,独自为他们界说资源不是好的做法。

资源露出的数据量也应考虑。假如你露出得太多，这会对服务器发生消沉的影响，特别是关于负载和功用。

上述状况和联系是在规划的API时需求要点考虑的要素，可以运用恰当的参数来处理。你可以扫描查询参数中limit参数来约束呼应数据量，或许让客户端运用途径参数来阻隔数据。

以咱们的相片同享运用作为示例。

它可以用于开发者获取在特定方位和特定主题标签中同享的一切相片的信息。 您或许还想要经过将每个 API 调用的成果数约束为 10，以减轻服务器负载。 假如终究用户想要找到波士顿的一切相片，并运用 winter 标签，则恳求将是：

GET/photos?location=boston&hashtag=winter&limit=10

留意现在的复杂性怎么被简化为一个与查询参数的简略相关。假如您想依据客户的恳求供给特定用户的信息，则调用：

GET/users/kesh92

这儿的 kesh92 是一个指定的用户名，它会回来该用户的地址和参加日期。

这仅仅朝着API齐备性进行参数规划的几种办法，可以协助用户更直观的运用你的API。

***， 有疑问时，暂时脱离它。假如你从头考虑了某个资源或调集的功用，应该把它放入下一个迭代中。开发和保护API是一个继续的进程，等候正确的用户反应可以构建一个强健的API，以协助用户以创造性的办法集成和开发运用程序。

API规划入门

没有一个API规划办法可以一了百了处理一切安排的问题。上述的主张仅仅是参阅定见和主张，能否选用取决于你的用户状况和需求。

一个API规划至关重要的首要原因是你的API能协助到终端用户，他们的需求便是贯穿你整个API规划的指明灯。