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