API 体系构建

前言

API 是模块或者子系统之间交互的接口定义。好的系统架构离不开好的 API 设计，而一个设计不够完善的 API 则注定会导致系统的后续发展和维护非常困难。在关键环节制定明确的 API 规范有助于 Service 对内提高产品间互通的效率，对外提供一致的使用体验，也有助于更好地被集成。

对于 API规范，比较知名的是 OpenAPI Specfication[1] 和 Google API Design Guide[2]。前者针对 RESTful API 设计在细节层面给出了非常具体的规定，已经成为 RESTful API 设计领域的事实标准，而后者则主要从云厂商的角度提出许多最佳实践性质的规范与建议，这些原则不仅仅适用于 RESTful API，也适合其他类型API设计。

虽然 RESTful 设计风格曝光率很高，但并不是所有云服务商都选择了完全遵循 RESTful，例如 AWS 和 阿里云 RPC 风格反而占了大多数，Google 和 Azure 则 RESTful 居多。

RESTful API 的优势是 HTTP 具备更好的易用性，让异构系统更容易集成，且开发执行效率比较高，面向资源要求也比较高。而 RPC API 可以使用更广泛的框架和方案，技术层面更底层也更为灵活，设计起来相对简单，掌握起来有一定门槛，架构上更加复杂。 RESTful 与 RPC 模式对比如下：

	RESTful API	RPC API
是否有统一规范	HTTP	无
面向资源	是	不确定
性能	中	高
通用性	高	弱
复杂度	中	高

如果强制统一风格，有些适合 RESTful 风格的服务非要使用 RPC 的话，看起来就会比较丑陋，如果只是一个过程化的服务调用，往 RESTful 资源化设计方向去靠会比较困难。但如果不强制使用统一风格，会造成针对API的体系化支持会更加复杂，例如为兼容两种风格 SDK 的自动化支持需要两套代码。

API接口入口：https://o0b.cn/anzexi

请求示例Curl PHP PHPsdk JAVA C# Python

-- 请求示例 url 默认请求参数已经URL编码处理 curl -i "https://api-gw.onebound.cn/taobao/item_get/?key=<您自己的apiKey>&secret=<您自己的apiSecret>&num_iid=652874751412&is_promotion=1"

响应示例

{"item": {"num_iid": "520813250866","title": "三刃木折叠刀过安检创意迷你钥匙扣钥匙刀军刀随身多功能小刀包邮","desc_short": "","price": 25.8,"total_price": 0,"suggestive_price": 0,"orginal_price": "25.80","nick": "欢乐购客栈","num": "832","min_num": 0,"detail_url": "http://item.taobao.com/item.htm?id=520813250866","pic_url": "//img.alicdn.com/imgextra/i4/2596264565/TB2p30elFXXXXXQXpXXXXXXXXXX_!!2596264565.jpg","brand": "三刃木","brandId": "4036703","rootCatId": "50013886","cid": "50014822","favcount": "4824","fanscount": "1469","crumbs": [],"created_time": "","modified_time": "","delist_time": "","desc": "<p style=\"text-align:center;\"><span style=\"color:#ff0000;\"><span style=\"font-size:24.0px;\"><strong>小店所有产品都支持刻字，如需刻字，拍之前联系客服即可。</strong></span></span></p> <p style=\"text-align:center;\"><span style=\"font-size:18.0px;\"><strong>炎炎夏日来临，一把随身携带便携式的折叠小刀，<span style=\"color:#ff0000;\">带开瓶器功能</span>，喝酒不用愁。（钥匙刀不带开瓶器功能）</strong></span></p> <p style=\"text-align:center;\"><strong style=\"color:#000000;line-height:1.5;\"><span style=\"font-size:18.0px;\"><span style=\"line-height:18.0px;\">可以当吊牌项链装饰，也可当钥匙扣挂饰， 水果刀 开瓶器 户外防身.</span></span></strong></p> <p style=\"text-align:center;\"><strong style=\"line-height:1.5;\"><span style=\"font-size:24.0px;\">部分客户跟我们反映链子质量还不够好，因此小店已重新订购一批质量更好的链子赠送，<span style=\"color:#ff0000;\">加量不加价</span>，只为让你买的更舒心，戴的更放心。</span></strong></p> <p style=\"text-align:center;\"><span style=\"font-size:36.0px;\"><strong>购买就送<span style=\"color:#ff0000;\">工具刀卡和链子</span>一条</strong></span></p> <p style=\"text-align:center;\"><span style=\"font-size:36.0px;\"><strong><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB2Sci2jXXXXXXFXpXXXXXXXXXX_!!2596264565.png\" size=\"611x442\"> </strong></span></p> <p style=\"text-align:center;\"><span style=\"font-size:18.0px;\"><strong>璀璨钻石套餐包含【SK016D钥匙扣+GJ019C折叠刀+GJ017D工具卡】</strong></span><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB2wWohmXXXXXX8XXXXXXXXXXXX_!!2596264565.jpg\" size=\"750x600\" /></p> <p style=\"text-align:center;\"><span style=\"font-size:18.0px;\"><strong>超凡大师套餐包括【304不锈钢钥匙扣+GJ019C折叠刀+GJ017D工具卡】</strong></span><a href=\"//item.taobao.com/item.htm?id=520798805877\" target=\"_blank\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i4/2596264565/TB2_uiXnFXXXXXBXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"float:none;margin:0.0px;\" /></a></p> <p style=\"text-align:center;\">&nbsp;</p> <p style=\"text-align:center;\"><span style=\"font-size:18.0px;\"><strong>最强王者套餐包括【钛钢钥匙扣+GJ019C折叠刀+GJ017D工具卡】<a href=\"//item.taobao.com/item.htm?id=520801586805\" target=\"_blank\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i4/2596264565/TB2Gm9xnFXXXXbmXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"float:none;margin:0.0px;\" /></a> </strong></span></p> <p style=\"text-align:center;\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB28Ox4b77OyuJjSsplXXXqdpXa_!!2596264565.jpg\" size=\"749x553\"> <img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i1/2596264565/TB2.mTddVXXXXbeXpXXXXXXXXXX_!!2596264565.jpg\" style=\"line-height:1.5;\" size=\"750x653\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB21Ro.jl0lpuFjSszdXXcdxFXa_!!2596264565.jpg\" size=\"750x653\"> <img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i4/2596264565/TB2q9CelVXXXXcUXXXXXXXXXXXX_!!2596264565.jpg\" size=\"750x340\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB21EX9lVXXXXaXXpXXXXXXXXXX_!!2596264565.jpg\" size=\"750x416\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB2udCylVXXXXXgXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i1/2596264565/TB2EARxjB8lpuFjSspaXXXJKpXa_!!2596264565.jpg\" size=\"750x515\"> <img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB2ssuwlVXXXXafXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i2/2596264565/TB2nAHqgyC9MuFjSZFoXXbUzFXa_!!2596264565.jpg\" size=\"750x606\"> <img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB2ahCelVXXXXc_XXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB2w1JnjwRkpuFjy1zeXXc.6FXa_!!2596264565.jpg\" size=\"750x469\"> <img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB2C902lVXXXXbnXpXXXXXXXXXX_!!2596264565.jpg_q90.jpg\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i1/2596264565/TB2sGR3lVXXXXblXpXXXXXXXXXX_!!2596264565.jpg_q90.jpg\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i1/2596264565/TB2ZBGxlVXXXXXMXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i1/2596264565/TB2MjWklVXXXXcaXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i2/2596264565/TB2UgV3lVXXXXbdXpXXXXXXXXXX_!!2596264565.jpg_q90.jpg\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i2/2596264565/TB2ip5XlVXXXXX2XpXXXXXXXXXX_!!2596264565.jpg_q90.jpg\"> <img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i2/2596264565/TB2sMTBdVXXXXXlXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"line-height:1.5;\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB2d3HfdVXXXXahXpXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"line-height:1.5;\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i4/2596264565/TB2AVbBdVXXXXXkXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"line-height:1.5;\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i2/2596264565/TB2nf_wdVXXXXaMXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"line-height:1.5;\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i4/2596264565/TB2dLYddVXXXXbtXpXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"line-height:1.5;\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i2/2596264565/TB2H1_adVXXXXbWXpXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"line-height:1.5;\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i2/2596264565/TB2eBzsdVXXXXbuXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"line-height:1.5;\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i4/2596264565/TB2dOTndVXXXXcCXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"line-height:1.5;\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i2/2596264565/TB2fK2tdVXXXXbkXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"line-height:1.5;\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i2/2596264565/TB29zjedVXXXXaFXpXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"line-height:1.5;\"><img align=\"absmiddle\" src=\"//img.alicdn.com/imgextra/i3/2596264565/TB2i7rmdVXXXXcTXXXXXXXXXXXX_!!2596264565.jpg_q90.jpg\" style=\"line-height:1.5;\" /></p>","item_imgs": [{"url": "//img.alicdn.com/imgextra/i4/2596264565/TB2p30elFXXXXXQXpXXXXXXXXXX_!!2596264565.jpg"},{"url": "//img.alicdn.com/imgextra/i2/2596264565/TB2onxRlVXXXXcDXpXXXXXXXXXX_!!2596264565.jpg"},{"url": "//img.alicdn.com/imgextra/i1/2596264565/TB2a.x.lVXXXXXPXpXXXXXXXXXX_!!2596264565.jpg"},{"url": "//img.alicdn.com/imgextra/i2/2596264565/TB2iWE6bKZkyKJjSszbXXblwFXa_!!2596264565.jpg"},{"url": "//img.alicdn.com/imgextra/i4/2596264565/TB2j2cTXib_F1JjSZFzXXc6KXXa_!!2596264565.jpg"}],"item_weight": "0","item_size": "","location": "广东深圳","post_fee": "","express_fee": "0.00","ems_fee": "","shipping_to": "广东广州白云区","has_discount": "false","video": [],"is_virtual": "","sample_id": "","is_promotion": "false","props_name": "1627207:1347647754:颜色分类:长方形带开瓶器+送工具刀卡+链子;1627207:1347647753:颜色分类:椭圆形带开瓶器+送工具刀卡+链子;1627207:1195392087:颜色分类:GJ018X钥匙刀+送工具刀卡+链子;1627207:1331112595:颜色分类:超凡大师套餐【送工具卡+链子】;1627207:1331112594:颜色分类:最强王者套餐【送工具卡+链子】;1627207:1331264247:颜色分类:璀璨钻石套餐【送工具卡+链子】","prop_imgs": {"prop_img": [{"properties": "1627207:1347647754","url": "//img.alicdn.com/imgextra/i3/2596264565/TB2.XeblVXXXXXkXpXXXXXXXXXX_!!2596264565.jpg"},{"properties": "1627207:1347647753","url": "//img.alicdn.com/imgextra/i4/2596264565/TB2dTrjdVXXXXXBXpXXXXXXXXXX_!!2596264565.jpg"},{"properties": "1627207:1195392087","url": "//img.alicdn.com/imgextra/i2/2596264565/TB2j22kdVXXXXXdXpXXXXXXXXXX_!!2596264565.jpg"},{"properties": "1627207:1331112595","url": "//img.alicdn.com/imgextra/i4/2596264565/TB2_uiXnFXXXXXBXXXXXXXXXXXX_!!2596264565.jpg"},{"properties": "1627207:1331112594","url": "//img.alicdn.com/imgextra/i4/2596264565/TB2Gm9xnFXXXXbmXXXXXXXXXXXX_!!2596264565.jpg"},{"properties": "1627207:1331264247","url": "//img.alicdn.com/imgextra/i3/2596264565/TB2wWohmXXXXXX8XXXXXXXXXXXX_!!2596264565.jpg"}]},"property_alias": "1627207:1347647754:长方形带开瓶器+送工具刀卡+链子;1627207:1347647753:椭圆形带开瓶器+送工具刀卡+链子;1627207:1195392087:GJ018X钥匙刀+送工具刀卡+链子;1627207:1331112595:超凡大师套餐【送工具卡+链子】;1627207:1331112594:最强王者套餐【送工具卡+链子】;1627207:1331264247:璀璨钻石套餐【送工具卡+链子】","props": [{"name": "品牌","value": "三刃木"},{"name": "产地","value": "中国"},{"name": "颜色分类","value": "长方形带开瓶器+送工具刀卡+链子,椭圆形带开瓶器+送工具刀卡+链子,GJ018X钥匙刀+送工具刀卡+链子,超凡大师套餐【送工具卡+链子】,最强王者套餐【送工具卡+链子】,璀璨钻石套餐【送工具卡+链子】"},{"name": "吊牌价","value": "46"},{"name": "功能数量","value": "5个及以下"},{"name": "货号","value": "GJ019C"},{"name": "附加功能","value": "开瓶器,刀,螺丝刀,钥匙圈,其他"}],"total_sold": "1","skus": {"sku": [{"price": "39","orginal_price": "39.00","properties": "1627207:1347647754","properties_name": "1627207:1347647754:颜色分类:长方形带开瓶器+送工具刀卡+链子","quantity": "104","sku_id": "3166598625985"},{"price": "39","orginal_price": "39.00","properties": "1627207:1347647753","properties_name": "1627207:1347647753:颜色分类:椭圆形带开瓶器+送工具刀卡+链子","quantity": "370","sku_id": "3166598625984"},{"price": "25.8","orginal_price": "25.80","properties": "1627207:1195392087","properties_name": "1627207:1195392087:颜色分类:GJ018X钥匙刀+送工具刀卡+链子","quantity": "34","sku_id": "3144644292458"},{"price": "73.8","orginal_price": "73.80","properties": "1627207:1331112595","properties_name": "1627207:1331112595:颜色分类:超凡大师套餐【送工具卡+链子】","quantity": "157","sku_id": "3161300228970"},{"price": "91.8","orginal_price": "91.80","properties": "1627207:1331112594","properties_name": "1627207:1331112594:颜色分类:最强王者套餐【送工具卡+链子】","quantity": "0","sku_id": "3161300228969"},{"price": "63.8","orginal_price": "63.80","properties": "1627207:1331264247","properties_name": "1627207:1331264247:颜色分类:璀璨钻石套餐【送工具卡+链子】","quantity": "167","sku_id": "3161107666655"}]},"seller_id": "2596264565","sales": "1","shop_id": "127203758","props_list": {"1627207:1347647754": "颜色分类:长方形带开瓶器+送工具刀卡+链子","1627207:1347647753": "颜色分类:椭圆形带开瓶器+送工具刀卡+链子","1627207:1195392087": "颜色分类:GJ018X钥匙刀+送工具刀卡+链子","1627207:1331112595": "颜色分类:超凡大师套餐【送工具卡+链子】","1627207:1331112594": "颜色分类:最强王者套餐【送工具卡+链子】","1627207:1331264247": "颜色分类:璀璨钻石套餐【送工具卡+链子】"},"seller_info": {"title": "欢乐购客栈","shop_name": "欢乐购客栈","sid": "127203758","zhuy": "//shop127203758.taobao.com","level": "12","shop_type": "C","user_num_id": "2596264565","nick": "欢乐购客栈","cid": null,"delivery_score": "4.8 ","item_score": "4.8 ","score_p": "4.8 "},"tmall": "false","error": "","warning": "","url_log": [],"stuff_status": "","shopinfo": {"shop_name": "欢乐购客栈","shop_id": "127203758"},"data_from": "mtop","method": "item_mtop:item_get","promo_type": null,"props_img": {"1627207:1347647754": "//img.alicdn.com/imgextra/i3/2596264565/TB2.XeblVXXXXXkXpXXXXXXXXXX_!!2596264565.jpg","1627207:1347647753": "//img.alicdn.com/imgextra/i4/2596264565/TB2dTrjdVXXXXXBXpXXXXXXXXXX_!!2596264565.jpg","1627207:1195392087": "//img.alicdn.com/imgextra/i2/2596264565/TB2j22kdVXXXXXdXpXXXXXXXXXX_!!2596264565.jpg","1627207:1331112595": "//img.alicdn.com/imgextra/i4/2596264565/TB2_uiXnFXXXXXBXXXXXXXXXXXX_!!2596264565.jpg","1627207:1331112594": "//img.alicdn.com/imgextra/i4/2596264565/TB2Gm9xnFXXXXbmXXXXXXXXXXXX_!!2596264565.jpg","1627207:1331264247": "//img.alicdn.com/imgextra/i3/2596264565/TB2wWohmXXXXXX8XXXXXXXXXXXX_!!2596264565.jpg"},