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:

• OAS (Open API Specification) 3.0 (formerly Swagger)

• RAML 1.0

• Blueprint

Columbia's Adoption of the OAS 3.0 API Contract Language

Columbia has deprecated RAML 1.0 as the API specification language and replaced it with OAS 3.0. 

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:

• {json:api}

• Hypertext Application Language (HAL)

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.

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/"
        }
    }
}