API接口设计

API - Application Programming Interface

语言本身提供的API
网络API（数据接口）- 免费开放（OpenAPI） / 付费

业务下沉 - 访问别人的接口 - urllib / requests / responses / http.client
业务上浮 - 提供数据接口给别人用 - djangrestframework - REST风格 - RESTful架构（风格）- ？

URL - 统一资源定位符 - 资源（名词） - CRUD - HTTP协议动词

REpresentation State Transfer

微服务架构 - 水平扩展

接口文档:

1. 接口的URL以及请求的方式（GET/POST/PUT/DELETE）
2. 请求这个接口可以做什么事情
3. 请求这个接口需要提供什么参数

• 参数名
• 数据类型
• 是否必填
• 有没有默认值
• 参数的位置（查询参数/表单参数/请求头参数）

4. 请求这个接口会返回什么样的数据

• XML / JSON / YAML
• 数据格式（包含的内容）
• 状态码代表什么含义

XML - eXtensible Markup Language - 异构系统之间交换数据 - 带结构的纯文本格式 - 事实标准

<?xml version="1.0" encoding="utf-8"?>
<messages>
<message>
<from gender="male">WangDachui</from>
<to>jackfrued</to>
<content>Dinner is on me!</content>
</message>
<message>
<from gender="female">Hellokitty</from>
<to>jackfrued</to>
<content>Dinner is on me!</content>
</message>
<message>
<from>WangDachui</from>
<to>jackfrued</to>
<content>Dinner is on me!</content>
</message>
</messages>

JSON - JavaScript Object Notation
[
{
'from': {
'name': 'Wangdachui',
'gender': 'male'
},
'to': 'jackfrued',
'content': 'Dinner is on me!'
},
{
'from': {
'name': 'Hellokitty',
'gender': 'female'
},
'to': 'jackfrued',
'content': 'Dinner is on me!'
},
{
'from': {
'name': 'Wangdachui',
'gender': 'male'
},
'to': 'jackfrued',
'content': 'Dinner is on me!'
}
]

YAML - Yet Another Markup Language
messages:
message:
from: WangDachui
gender: male
to: jackfrued
content: Dinner is on me!
message:
from: Hellokitty
gender: female
to: jackfrued
content: Dinner is on me!
message:
from: WangDachui
to: jackfrued
content: Dinner is on me!

在线API文档和测试数据生成 - Swagger-UI / RAP2
[图片上传失败...(image-bd8d4-1543990291898)]

https://swagger.io/
[图片上传失败...(image-405a51-1543990291898)]

http://rap2.taobao.org - 新版
[图片上传失败...(image-fd31e-1543990291898)]

http://rapapi.org/org/index.do - 旧版

rst格式(reStructuredText) ----|
|------- pdf / word
md格式(Markdown) ----|

POSTMAN - 接口测试