Restful API设计规范(参考)

Restful API 特点

Resource : 一切面向资源,Url中的资源使用名词复数,原则上不使用动词;

    例如:资源是:cars、fences
    http://api.xyz.com/v1/cars
    http://api.xyz.com/v1/fences

Collection :资源的集合,使用资源的复数形式;
Version : 所有的API必须制定版本号,新的版本建议对之前版本API做兼容性处理;

    http://api.xyz.com/v1/cars
    http://api.xyz.com/v2/cars

HTTP Verb :使用Http动词来实现资源的增删改查;

    GET:用于获取资源,返回资源对象实体或集合;
    POST:用于新增资源,返回新增的资源实体;
    PUT:用于修改资源,返回修改后的资源实体;
    DELETE:用于删除资源,返回空;

HTTP Status :使用Http状态码作为业务状态码;

    200:请求资源成功,返回请求的数据对象或列表;
    201:创建/修改资源成功,返回操作完成的数据对象,如有敏感数据,在业务层脱敏;
    204:删除资源成功,返回空;
    400:请求失败(参数错误或服务端捕获的错误);
    401:未授权(需要重新登录);
    403:没有权限访问资源;
    404:请求的资源不存在;
    500:服务器内部错误;

JSON :使用JSON传输数据,包括接口返回,新增、修改传输数据;


接口请求参数

注意:所有接口的请求参数中,全部使用小写字母,如果属性有多个单词组成,使用下划线连接

1.如果是请求某个具体的资源,该参数将作为请求url的一部分,例如:

    GET         http://api.xyz.com/v1/cars/58
    DELETE      http://api.xyz.com/v1/users/10556054

2.如果进行添加、修改操作,需要传输结构化的数据,则使用Json Object:

    POST            http://api.xyz.com/v1/cars
    data: {
        "username": "admin01",
        "password": "123456",
        "organization_id": 192
    }
    PUT         http://api.xyz.com/v1/cars
    data: {
        "id": 12,
        "username": "admin01",
        "password": "123456",
        "organization_id": 192
    }

3.如果是分页、排序等表示过滤的意义参数,使用字符串拼接url的方式:

    GET         http://api.xyz.com/v1/cars?page=1&page_size=10

接口返回模板

注意:所有接口的返回数据的参数中,全部使用小写字母,如果属性有多个单词组成,使用下划线连接

在Restful API中,可以直接使用Http状态码来表示业务执行的结果,考虑到执行成功时,msg字段并没有什么实际意义。所以Restful API接口可以直接返回data中的数据。
例如:请求 http://api/xyz.com/v1/cars/58 ,返回

Http Status: 200
Response Body:
    {
        "id": 58,
        "name": "audi",
        "color": "write
    }

或者没有请求到的时候

Http Status: 404
Response Body:车辆不存在

如果请求的是列表,同样需要返回列表本身,列表总数,页面等相关数据。例如请求 http://api/xyz.com/v1/cars?page=1&page_size=10

Http Status: 200
Response Body:
    {
        "list": [
            {},{},{}
        ],
        "total": 141,
        "page":1,
        "page_size":10
    }

参数说明及规约:关于分页获取列表数据,统一使用参数命名和格式

字段名称 字段类型 说明
list array 查询到的数据列表
total int 该查询条件下的总记录数量
page int 当前所在页
page_size int 每页显示记录数
最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 230,578评论 6 544
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 99,701评论 3 429
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 178,691评论 0 383
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 63,974评论 1 318
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 72,694评论 6 413
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 56,026评论 1 329
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 44,015评论 3 450
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 43,193评论 0 290
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 49,719评论 1 336
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 41,442评论 3 360
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 43,668评论 1 374
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 39,151评论 5 365
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 44,846评论 3 351
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 35,255评论 0 28
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 36,592评论 1 295
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 52,394评论 3 400
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 48,635评论 2 380