An API Contract is a machine- and human-readable document that API producers and consumers agree to abide by. The contract uses standard language to define data types (schemas), URI (resource) names, URI and query parameters, applicable HTTP methods (GET, POST, etc.) and security mechanisms.
Some Contract Language Specifications:
Columbia's Adoption of the RAML 1.0 API Contract Language
Columbia has selected RAML 1.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}
API Content Specifications
While the API contract language standardizes mechanisms for describing APIs in a general way, we need a more specific mechanism to make our API implementations consistently understood.
Some API content standards:
Columbia's Adoption of the JSON API 1.0 API Content Specification
Columbia has select {json:api} as the specification language due largely to its simplicity. HAL just felt like overkill.
One must set Content-type: application/vnd.api+json to indicate the {json:api} is used.
TODO: Add {json:api} example.