RESTful API

RESTful API 是一种API规范，使用的是raml（RESTful API Modeling Language）文件，讲到这个，也得扯到wsdl文件，它是用来描述soap（简单对象传输协议）API的，但是这个协议比较重，所以现在推行的是RESTful。

然后的话，这个怎么创建怎么使用呢?

我用的是Anypoint Platform平台上的Design Center来创建API，并且进行模拟测试的。

 

先上文件再说，不然我都不知道说些啥，我感觉我想说多点东西的，但写的时候就没几个字了。

#%RAML 1.0
version: v1
title: American Flights API

types:
  AmericanFlight: !include /exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml

traits:
  client-id-required:
    headers:
      client_id:
        type: string
      client_secret:
        type: string
    responses:
      401:
        description: Unauthorized, The client_id or client_secret are not valid or the client does not have access.
      429:
        description: The client used all of it's request quota for the current period.
      500:
        description: An error ocurred, see the specific message (Only if it is a WSDL enpoint).
      503:
        description: Contracts Information Unreachable.

/flights:
  is: [client-id-required]
  get:
    queryParameters:
      destination:
        required: false
        enum: 
          - SFO
          - LAX
          - CLE
    responses:
      200:
        body:
          application/json:
            type: AmericanFlight[]
            examples:
              output: !include /exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flights-example/1.0.1/AmericanFlightsExample.raml
  post:
    body:
      application/json:
        type: AmericanFlight
        examples:
          input: !include examples/AmericanFlightExample.raml
    responses:
      201:
        body:
          application/json:
            example: 
              message: Flight added(but not really)

  /{ID}:
    is: [client-id-required]
    get:
      responses:
        200:
          body:
            application/json:
              type: AmericanFlight
              examples:
                output: !include examples/AmericanFlightExample.raml
    delete:
      responses:
        200:
          body:
            application/json:
              example:
                message: Flight deleted (but not really)
    put:
      body:
        application/json:
          type: AmericanFlight
          examples:
            input: !include examples/AmericanFlightNoIDExample.raml
      responses:
        200:
          body:
            application/json:
              example:
                message: Flight updated (but not really)

raml的格式就是十分简单清晰，以#%RAML 1.0为开头，然后下面是title，然后的话，就可以写相应的路径内容。每一层是一个层级，层次感很明确，回车之后tab就可以到下面去。然

整个结构就是，

先定义raml的文本信息，

然后的话，就犹如声明变量一样，定义一些类型types，方便之后使用，定义一些请求过来的方法体要用到的类型，可以进行相应的类型匹配，这个可以直接写，也可以通过 !incude 引用raml文件或者引用json文件。

然后的话，可以添加一些强制参数，下面这个是我的raml的强制参数图，这个是强制在headers那里必须要有client_id和client_secret的这两个参数，不然的话，是无法call通的。

然后接下来就是写相应的资源，比如 /flights: 这个就是定义一个资源，接下来，如上面写的

 

/flights:
  is: [client-id-required]
  get:

加了这个，相当于把那个必须要client_id和client_secret参数放到这个资源上面，和is同级的get就是相应的method，所以能替换这个的还可以是post、put、delete等这些method，

然后的话，现在变的地方就多了，你可以写queryParameter，然后往下面添加参数，参数可以设置成必须和非必须的，通过required的true或false来进行设置，参数可以设置成可选列表;如果此时你是post方法的话，那么就要写body，然后在下面写body的类型，通常是application/json，然后type就要被用上了

post:
    body:
      application/json:
        type: AmericanFlight
        examples:
          input: !include examples/AmericanFlightExample.raml

type上写入类型名，然后examples是一个示例请求，通过input: !include来包含，当然也可以是json，一样的。example也是可以的，主要是看它的请求。

然后的话，再下一层就要回退到和body同层，或者是结构上的method的下一层，写response，然后响应的话，就会有个响应码，对应的响应码可以有对应的body返回，body下面一样要写格式，如application/json，如果要返回的示例是在raml或者json中，那么一样要写type，然后引入相应的示例。

大概整个raml文件就是这样，然后的话，在Anypoint Platform中，可以进行mocking service，然后可以使用postman工具等来call这个API，还是比较方便的。