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,还是比较方便的。