Skip to content

What is contract

Jump to bottom
Kacper Walanus edited this page Mar 12, 2016 · 1 revision

IN PROGRESS

Contract is a git repository which:

  • Is downloadable for all who wants to use it.
  • Contains one or more *.contract.json file(s). Contract itself is described in these files.
  • All *.contract.json files have format described below.

Contract schema

  {
    "schema": {
      "request": {
        "method": string,       // GET, POST, ...
        "path": string          // /users/:id/notes
      }
    },
    "examples": [
      {
        "request": {
          "headers": object,    // { "Content-Type": "application/json" }
          "params": object      // { "id": 22 }
        },
        "response": {
          "body_path": string   // /path_to_file/with/response.json
        }
      }
    ]
  }

Schema description

####schema.request.method string, case insensitive

Possible values: "get", "post", "put", "patch", "delete", "options".

Example:

  {
    "schema": {
      "request": {
        "method": "delete"
      }
    }
  }

####`schema.request.path` _string, case sensitive, starts with `/`_

URI pattern. Example values:

  • /users
  • /users/:id
  • /users/{id}
  • /users/:id/posts
  • /users/:id/posts/:post_id
  • /users/{lang}_dictionary/items.

If path is /users/:id/posts/:post_id, sending request to /users/2/posts/33 means that id parameter equals 2 and post_id parameter equals 33.

Example:

  {
    "schema": {
      "request": {
        "path": "/users/:id/posts"
      }
    }
  }

####`examples` _list of [Response objects](https://github.com/kv109/contracto_sample-contract/wiki/Contract-format#requestresponses-1)_

List of possible responses. Which response will be returned depends on request.responses[].request. Response will be returned only if request meets criteria described in request.responses[].request.


####`examples[]` _object, required keys: [response](https://github.com/kv109/contracto_sample-contract/wiki/Contract-format#requestresponsesresponse), optional keys: [request](https://github.com/kv109/contracto_sample-contract/wiki/Contract-format#requestresponsesrequest)_

Response object.


####`examples[].response` _object, optional keys: body, body_path_

One of optional keys must be present.


####`examples[].response.body_path` _string, starts with `/`_

Path to file with response body. Content of this file will be returned as a server response. Path is absolute, so /users/1.json means {dir_with_your_contract_repository}/users/1.json.

{
  "examples": [
    {
      "response": {
        "body_path": "/users/1.json"
      }
    }
  ]
}

####`examples[].request` _object, optional keys: headers, params_
####`examples[].request.headers` _object_

Object with HTTP request headers. Response will be served only if HTTP request contains each header this object also contains.

Example:

{
  "examples": [
    {
      "request": {
        "headers": {
          "Content-Type": "application/json"
        }
      }
    }
  ]
}

####`examples[].request.params` _object_

Object with request params. Response will be served only if HTTP request contains each param this object also contains.

Example:

{
  "schema": {
    "request": {
      "path": "/users"
    }
  },
  "examples": [
    {
      "request": {
        "params": {
          "search": "John",
          "page": 2
        }
      }
    }
  ]
}

Requests with following URI meet criteria above:

  • /users/John?page=2
  • /users/John?page=2&per_page=50

Requests with following URI do not meet criteria above:

  • /users/John?page=3
  • /users?search=John&page=2
  • /posts/John?page=2
Clone this wiki locally