RESTful Api设计风格

协议:API 与用户的通信协议,总是使用 HTTPS 协议

域名:应该尽量将 API 部署在专用域名之下,如果确定 API 很简单,不会有进一步的扩展,可以考虑放在主域名之下。

版本

应该将 API 的版本放在 URL 中:https://www.sunck.wang/api/v1.0
将版本号放在 HTTP 头信息中:https://www.sunck.wang/students
路径:表示 API 的具体网址,每个网址代表一种资源,所以网址中不能有动词,只能有名词,并且所用的名词往往与数据库的表名对应。数据库中的表示记录同种数据的集合,所以 API 中的名词也应该使用复数。

获取所有学生:

https://www.sunck.wang/api/v1... 错误写法
https://www.sunck.wang/api/v1... 正确写法

使用正确的 HTTP 请求方法

例子

过滤信息

如果资源数较多,服务器不能将所有数据一次全部返回给客户端,API 应该提供参数,过滤返回结果

例子

注意:参数的设计允许存在冗余,即允许 API 路径和 URL 参数偶尔有重复

状态码

服务器向客户端返回的状态码和提示信息

错误处理

如果错误码是4xx,就应该向用户返回错误信息,一般来说,返回的信息中将 error 作为键名,出错的信息作为键值即可

{
    error:'Invalid API KEY',
}

响应结果

针对不同的操作,服务器向用户返回结果应该符合规范

使用链接相关的资源

返回结果中提供了链接,链向了其他的 API 方法,使得用户不查看文档,也知道下一步应该做什么

示例

{
    link:"www.sunck.wang/grades/"
}
{
    "link":{
        "rel":"collection www.sunck.wang/index/",
        "href":"www.sunck.wang/grades/",
        "title":"List of Grades",
        "type":"application/json",
    }
}

rel:表示这个 API 与当前网址的关系

href:表示 API 路径

title:表示 API 的标题

type:表示返回的类型

其他:服务器返回的数据尽量使用 JSON 格式,避免使用 XML 格式

API 文档规范要求

一、 写明该接口的功能是什么

二、 请求的 URL 是什么

三、 请求方式是什么(POST、GET、 DELETE、PUT、 PATCH等)

四、 参数是什么,此处还需说明你的参数名、参数类型、是否必填、参数的简单解释

五、 请求成功时的响应内容(实际开发中,要与前端同事沟通使用什么样的数据结构),并且对其中的字段做出说明(包括含义、数据类型,数据结构<字符串,数组,字典等>)

六、 请求失败时的响应内容,并且对其中的字段做出说明(包括含义、数据类型,数据结构<字符串,数组,字典等>)包括单独的对错误码的说明

七、 请求样例(返回结果部分要包括成功的情况和失败的情况)

八、 最好写上文档的编写人和编写时间(可不写)

Demo:

  • 功能:获取某人的下属

  • URL:”people/api/v1/ subordinate”

请求参数说明:

请求成功参数说明

data 内的响应参数说明

请求失败参数说明


code值说明

Code 说明
1 成功
2 该人已经离职
3 请求参数不完整
4 参数类型错误
样例:

请求参数 uid 1

# 请求成功样例
{
    ,
    'msg': 'ok',
    'data':[
        {
        ,
        'name': 'Tom',
        'position': '教师'
        },
        {
        ,
        'name’: 'Lucy',
        'position': '助教'
        }
    ]
}

# 请求失败样例
    {
        ,
        'msg': '该人已离职'
}

作者:rottengeek
原文链接:http://t.cn/RgC0MIP

第 19 期Python实战班正在火热招生中
第 8 期自动化运维班正在招生中
第4 期 golang 正在招生中

详情扫码咨询

免费视频 戳戳戳!

Django—— restful 设计风格的更多相关文章

  1. Django RESTful Web Services, 此书学DRF不错

    全名为<Django RESTful Web Services: The easiest way to build Python RESTful APIs and web services wi ...

  2. 在django restful framework中设置django model的property

    众所周知,在django的model中,可以某些字段设置@property和setter deleter getter,这样就可以在存入数据的时候进行一些操作,具体原理请参见廖雪峰大神的博客https ...

  3. 4- vue django restful framework 打造生鲜超市 -restful api 与前端源码介绍

    4- vue django restful framework 打造生鲜超市 -restful api 与前端源码介绍 天涯明月笙 关注 2018.02.20 19:23* 字数 762 阅读 135 ...

  4. 3- vue django restful framework 打造生鲜超市 - model设计和资源导入

    3- vue django restful framework 打造生鲜超市 - model设计和资源导入 使用Python3.6与Django2.0.2(Django-rest-framework) ...

  5. django restful framework 一对多方向更新数据库

    目录 django restful framework 序列化 一 . 数据模型: models 二. 序列化: serializers 三, 视图: views 四, 路由: urls 五. 测试 ...

  6. $Django RESTful规范

    一 什么是RESTful REST与技术无关,代表的是一种软件架构风格,REST是Representational State Transfer的简称,中文翻译为“表征状态转移” REST从资源的角度 ...

  7. Django restful

    1.restful api的规范 API与用户的通信协议,总是使用HTTPs协议. 域名  https://api.example.com                         尽量将API ...

  8. RESTFUL 设计风格

    RESTFUL  规范总结: Rest是web服务的一种架构风格;使用HTTP,URI,XML,JSON,HTML等广泛流行的标准和协议;轻量级,跨平台,跨语言的架构设计;它是一种设计风格,不是一种标 ...

  9. 7- vue django restful framework 打造生鲜超市 -商品类别数据展示(上)

    Vue+Django REST framework实战 搭建一个前后端分离的生鲜超市网站 Django rtf 完成 商品列表页 并没有将列表页的数据json 与前端的页面展示结合起来 讲解如果将dr ...

随机推荐

  1. WinPE ISO制作

    1.安装ADK,然后导出winPE镜像文件和启动文件: 打开 部署和映像工具环境,cd "Windows Preinstallation Environment",运行 copyp ...

  2. 生活随记[All]

    1. 心灵鸡汤[all] 2. 工作总结 [all] 3. 面试经验[all] 4. 其他

  3. Linux grep/egrep命令详解

    grep命令是一种强大的文本搜索工具,它能使用正则表达式搜索文本,并把匹 配的行打印出来 grep搜索成功,则返回0,如果搜索不成功,则返回1,如果搜索的文件不存在,则返回2. grep的规则表达式( ...

  4. VRSProcess(二)

    1._beginthreadex再谈 Windows操作系统提供了这样的一种解决方案——每个线程都将拥有自己专用的一块内存区域来供标准C运行库中所有有需要的函数使用.而且这块内存区域的创建就是由C/C ...

  5. Programming Assignment 4: Boggle

    编程作业四 作业链接:Boggle & Checklist 我的代码:BoggleSolver.java 问题简介 Boggle 是一个文字游戏,有 16 个每面都有字母的骰子,开始随机将它们 ...

  6. DotNET中的幕后英雄:MSCOREE.DLL

    现在做.NET Framework的开发的朋友应该是越来越多了,但是可能并非人人都对MSCOREE.DLL非常了解.而事实上,毫不夸张地说,MSCOREE.DLL是.NET Framework中最为核 ...

  7. codeforces 293E Close Vertices

    题目链接 正解:点分治+树状数组. 点分治板子题,直接点分以后按照$w$排序,扫指针的时候把$w$合法的路径以$l$为下标加入树状数组统计就行了. 写这道题只是想看看我要写多久..事实证明我确实是老年 ...

  8. hdu2824 The Euler function(欧拉函数个数)

    版权声明:本文为博主原创文章,未经博主同意不得转载. vasttian https://blog.csdn.net/u012860063/article/details/36426357 题目链接:h ...

  9. Docker镜像搭建Linux下samba共享目录

    Samba 是 SMB/CIFS 网络协议的重新实现, 它作为 NFS 的补充使得在 Linux.OS/2.DOS 和 Windows 系统中进行文件共享.打印机共享更容易实现.SMB协议是客户机/服 ...

  10. kubeadm init 时从本地私有仓库下载镜像

    #kubeadm init 时从本地私有仓库下载镜像 images=( gcr.io/google_containers/kube-proxy-amd64:v1.6.1 gcr.io/google_c ...