题目描述

写接口是工程师的基本功。先看看写得好的接口返回的数字是什么样子，文档是什么样子。

https://web-api.coinmarketcap.com/v1/cryptocurrency/ohlcv/historical?symbol=BTC&convert=USD&time_start=1612556000&time_end=1612656000

请求比特币历史数据的接口，公网的开发接口，无需认证。

{
    "status": {
        "timestamp": "2021-02-08T06:19:27.474Z",
        "error_code": 0,
        "error_message": null,
        "elapsed": 12,
        "credit_count": 0,
        "notice": null
    },
    "data": {
        "id": 1,
        "name": "Bitcoin",
        "symbol": "BTC",
        "quotes": [
            {
                "time_open": "2021-02-06T00:00:00.000Z",
                "time_close": "2021-02-06T23:59:59.999Z",
                "time_high": "2021-02-06T16:02:41.000Z",
                "time_low": "2021-02-06T00:00:37.000Z",
                "quote": {
                    "USD": {
                        "open": 38138.38833975,
                        "high": 40846.54690329,
                        "low": 38138.38833975,
                        "close": 39266.01073494,
                        "volume": 71326033652.98,
                        "market_cap": 731192490092.84,
                        "timestamp": "2021-02-06T23:59:59.999Z"
                    }
                }
            }
        ]
    }
}

可以看到里面有 status, data 两部分，status 里面有 error_code, error_message，出错了是什么情况，啥错误信息。

思路点拨

文档效果是上面的样子，每一个参数，每一种状态码都详细解释，这些都要在代码里实现。所以说写接口看似简单的基本功，但要写出靠谱的接口，工作量不小，前期合理的规划不能少。之前为配合讲解免费课《Django REST framework 前后端分离框架实践》转载过一篇手记，（转）深入理解什么是 RESTful API。提到了 10 点 RESTful 设计指南，这里在重复一下：

1. 协议
2. 域名
3. 版本（Versioning）
4. 路径（EndPoint）
5. HTTP 动词
6. 过滤信息（Filtering）
7. 状态码（Status Code）
8. 错误处理（Error Handling）
9. 返回结果
10. Hypermedia API

能把上面 10 点都做到，你写的接口肯定靠谱。要不然就是用的人不靠谱…（大家要学会甩锅给前端）。

欢迎大家补充，以上 10 点是否能解决你在实际开发中遇到的的问题。