...
Some Contract Language Specifications:
Columbia's Adoption of the
...
OAS 3.0 API Contract Language
Columbia has selected RAML deprecated RAML 1.0 as 0 as the API specification language primarily because it is the language supported by MuleSoft. In order to support open standard and collaboration with other standards like OpenAPI/Swagger 3.0, Columbia's integration team can convert the specifications from RAML to Swagger and vice-versa. MuleSoft has announced a future direction to support OpenAPI 3.0 so we will keep an eye on the standards and might revisit the selection in FY18. It is likely that we will eventually deprecate RAML 1.0 in favor of OpenAPI.
TODO: Add RAML example.
How to get RAML from your application?
RAML can be downloaded from APIkit application using following URI: /<app>/<version>/console/api/?raml. This downloads the root RAML for the project. ”!include” files are also available with a URI of /<app>/<version>/console/api/<included>.raml {where included in the relative path of the raml file}
and replaced it with OAS 3.0.
API Content Specifications
...
One must set Content-type: application/vnd.api+json to indicate the {json:api} is used.TODO: Add {json:api} example..
Following is a jsonapi response example showing:
- The data with mandatory type and id
- The attributes for this particular type.
- Relationships data for the (plural) locations relationship which contains types and ids only.
- Links metadata for the self reference for this item (and the enclosed self link for the relationships)
{
"data": {
"type": "Widget",
"id": "91e5e32e-864f-4d1d-813a-bbd5c46b325d",
"attributes": {
"name": "can opener",
"qty": 43
},
"relationships": {
"locations": {
"data": [
{
"type": "Location",
"id": "1a5a18bf-8afa-410d-83d3-b4c89155b32f"
},
{
"type": "Location",
"id": "805044c9-9a6a-454a-962c-a90ec3f94def"
}
],
"links": {
"self": "http://34.239.103.140:8000/v1/api/widgets/91e5e32e-864f-4d1d-813a-bbd5c46b325d/relationships/locations"
},
"meta": {
"count": 2
}
}
},
"links": {
"self": "http://34.239.103.140:8000/v1/api/widgets/91e5e32e-864f-4d1d-813a-bbd5c46b325d/"
}
}
}