Rest-Homework---记一次raml

前言

这是我第一次写raml,一开始杂乱无章没有从宏观角度去思考,什么都想加进去,导致越来越复杂,后来在李老师指导下抽丝剥茧,才看清楚raml真正的意义。

摘要

RAML 是一种基于HTTP-API的定义语言. 体现了所有对象传输状态的原则 . RAML基于YAML ,依靠标准和最佳实践从而编写更高质量的API . 生成全面的用户文档 .
RAML通过一个格式来提供规范的接口.作为API提供者和使用者之间的合约.用户可使用文档实现客户端和服务器的交互.

组织结构

  • 基本信息 解释了如何描述核心API的方面,如它的名称、标题、位置(URI)和违约。
  • 数据类型 描述了一种通过简化模型API数据类型系统,也包括JSON和XML模式。
  • 资源 描述了如何指定一个API的资源和嵌套的资源,以及在任何URI URI参数模板,所有一类事物从宏观讲都是一类,同一类中事物具有不同的性质,但是raml不考虑性质uri指向的就是资源,所有的操作方法只是对uri所指向的资源的操作,和uri本身并没有关系。
  • 方法 描述了如何指定API的资源上的method,以及他们的请求头,查询参数和请求,一般的有四个主要的method,post添加,get查询,put更新,delete删除。
  • 响应 描述API规范的反应,包括状态码、媒体类型,响应头和响应,一般有200-请求成功,404- 请求的资源不存在,500-服务器内部错误,。
  • 资源类型和特征 描述可选机制使用RAML资源类型和特征描述资源,避免不必要的重复在一个API的定义和促进一致性和重用,在对同一路径下的资源进行操作可以合并操作,对于get和post要理解输入什么,输出什么。
  • 安全 描述了机制中可用RAML指定一个API的安全方案。
  • 注释 描述了扩展机制RAML规范通过定义强类型的注释和应用规范。
    Includes,Libraries 覆盖以及扩展 描述了一个API的定义可能是由外部化定义文件,如何打包成库集合的定义,如何分离和覆盖层的元数据的RAML文档,以及一个API规范与附加功能可以扩展。

出现的问题以及解决方法

1.首先拿到需求时, 没有仔细对需求分析,需求中的三个接口,个人却又加入太多的个人定义,直接导致后面越来越复杂无法进行下去,其实首先拿到需求应该是做减法,先从满足最简单功能的开始,设计raml的初衷就是化繁为简,如同一张总施工图,指导每一步,但不过问每一步具体实现。

2.对资源定义理解不够深刻,人为给资源进行分类,没有对整体进行把握,比如我和plant都是同一个属性,当定义了plant是研发部领导的时候才有上下级关系,查找我只要在plant下面进行检索。

3.uri理解的偏差,raml里面包含,uri和method,uri就好比指的是资源的路径,method才是对资源操作的方法,这个理解是最重要的,之前我定义的/inputnode,/findnode,/allnode,相当于在三个路径里面对三个文件进行操作,只要理解到uri是路径,需求里所有的操作都是指向一个路径操作。

4.需求中输入节点返回节点及其子孙节点,/api/Nodes/{valuename},这里面valuename就是要查询的节点

/api/Nodes:
   /{valuename}:
       get:
         description: Get Total Value Xml information
         displayName: ValueNodeXml
         responses:
           200:
             body:
               application/xml:
                 type: HierarchyNode
           404:
           500:

5.http主要有四种方法,post添加,get查找,put更新,delete删除,在uri路径上进行操作方法选择上由于之前理解的偏差出错

6.在现有的需求里post不会有404,在get里面才有404,但是也要看实际情况,例如

7.post是输入body里是输入的资源,存储成功返回200,服务器错误返回500

  post:
      description: Obtain storage resources
      displayName: StorageResource
      body:
         application/json:
           type: HierarchyPath
      responses:
         200:
         500:

总结反思

我是半路转行培训学的java,计算机相关的基础知识知道甚少,数据结构一知半解,培训后总是把学到的东西作为一种标准来对比新接触的东西,这是一件很可怕的事情,在编程的行业的没有什么是一成不变的标准,时刻都在变换的行业里,就好比自己是一个小杯子装满了各个地方收集来水,以至于现在再也装不下更多,只有放空自己,才能装得下更多的东西。

你可能感兴趣的