API 英文是 Application Programming Interface 的简写，中文是应用编程接口之意，用于对接两个应用间的数据和消息，以及函数调用等。
APP 是面向最终用户，API 是面向软件开发者。
-
优秀的 API 文档
表述干净利索，写清楚函数说明，参数，返回值就可以。
-
稳定与一致性
无论有没有庞大的用户群，API 设计者都不要轻易做修改。比如多版本运行，比如对老版本应用支持相当长的一段时间，甚至是几年。
从一开始就明确地 URL 命名为一个版本号。
除非你有很详实的数据表明，老版已经无用户，我们当然在某个时候逐步淘汰以前的版本。在还有用户的时候，需要继续维护，然后给用户足够的提示，并提供足够好的过渡计划。
另外，除了随着时间的推移，保持 API 稳定性，比如内部函数保持一致。在 API 中处理好参数，尽量使用相同或共享的参数体系，如在整个 API 中使用相同的命名约定和数据返回。
有时候实在不得已需要修改，尽量能够最小差异的做改变。每次更新，我们可以记录和发布 API 更新的文档，告诉调用者 API 的版本差异，详细说明如何升级。
-
灵活性
灵活性，表示输入灵活，输出多样，这尤其适用于开放平台的 API 开发者。调用的开发者，有个人开发者，公司，有网站，有 APP，还有各种应用软件，客户端平台并不是一致的，有的可能还不支持 JSON，不支持 OAuth 等。
所以在设计 API 时，要有一定的灵活性和格式宽容，对于你的输入和输出的限制这是很好的。
API 可以支持多种输出，如 XML、JSON、YAML 等格式。但在 URL 请求是一致的，如/api/v1/component。也可以接受请求类似 application/json 的 HTTP 头，或者支持 URL 的 GET 参数变量，如?version=json 等。
为了容错，对参数可以忽略大小写，让调用者减轻不必要的挫折。输入的参数也可以做到多种格式，比如 GET 和 POST 方法都支持，格式可以为变量，也可以是 json 和 XML。
支持多数的标准的输入输出，可以最大化的让 API 具备灵活性，不在是我们个人的技术偏好。
-
安全性
安全是 API 相当重要的任务。对于内容型的 API，如果没有私密的数据传输，当然可以不设置鉴权。但对于一些数据敏感的数据来说，需要对调用的用户进行身份验证鉴权。
对于大多数 API，可以使用简单的基于 token 的身份验证。token 是一个哈希分配给调用者，允许通过 POST 或 HTTP 请求。比如可以用 sha1 或 MD5 的哈希字符串给到调用者，也可以使用 DES 的方式。
一个安全的 token，最好不只是一串标识符，不可逆当然是最好的。
另一个使用广泛的方法，可以采用 OAuth 2.0 + SSL。
现在的时代，无论如何都得使用 SSL。另外 OAuth 2.0 也已经成为服务器端验证的标准，大多数开发语言都有成熟的把持。
Web API 大多需要支持 JavaScript 调用，如 JQuery 等库来获取数据。这时需要严格验证来源，以保证非授权网站调用，防止用户数据丢失或被窃取。
可以使用白名单或用户角色处理。比如可以通过用户分级来对限制数据的创建、读取、更新和删除等操作。比如只有授权用户才可以调用诸如/user/delete/id。如果未经授权，返回错误消息，比如 406 响应。
另外，还要避免 API 受跨站请求伪造（CSRF）攻击。一些 API 应用会有 session 或 cookie 认证，一定要注意 CSRF 跨站。比如有一个请求来查看用户的详细信息（如 account/card/view/152423），需要在代码中检查 ID=152423 是指经过授权访问的资源。
为此，API 需要严密验证输入数据，包括数据完整性和数据精度，以保证所有来自用户的输入能够精确解析。
可以对 API 请求的历史进行日志记录，包括次数，频率，异常时及时报警。