added documentation on using hooks

.bundle/config

@@ -0,0 +1,2 @@
+---
+BUNDLE_PATH: "vendor/bundle"

Gemfile.lock

@@ -72,7 +72,8 @@ GEM
 
 PLATFORMS
   ruby
-  x86_64-linux-musl
+  universal-darwin-20
+  x86_64-linux
 
 DEPENDENCIES
   jekyll

documentation/api_gateways.md

@@ -0,0 +1,53 @@
+---
+layout: default
+title: API Gateways
+parent: Documentation
+nav_order: 26
+---
+API Gateways
+============
+
+## Four Party Model
+
+A contract represents the interface provided by the API provider to the API consumer.
+
+An API gateway may modify this interface, adding headers, rewriting the URL, etc. As a result, the contract seen by the consumer may be a little different from that seen by the provider.
+
+In addition, there may be consumers of the API lying behind the API gateway, consuming the API directly.
+
+We can think of this as a four party model.
+
+![four party model](/images/four-party-model.svg)
+
+Specmatic's approach is to write the contract the way the API provider and internal consumer sees it.
+
+This way, the API provider can run contract tests using the contract as is, and the internal consumer can stub it out.
+
+That leaves the external consumer.
+
+Specmatic provides a hook that can be configured by the external consumer to load whenever the API is stubbed out. The hook is given the contract, and can modify it in memory just before it is loaded.
+
+The hook name is `stub_load_contract`.
+
+Register it in [specmatic.json](/documentation/specmatic_json.html#hooks) in the section on hooks.
+
+The hooks snippet in specmatic.json would look like this:
+
+```json
+  "hooks": {
+    "stub_load_contract": "python load.py"
+  }
+```
+
+It can be any command, above is just an example.
+
+Instead of reading the contract directly, Specmatic runs "python load.py" with the environment variable `CONTRACT_FILE` set to the path of the contract to be read.
+
+`load.py` must read the contract, modify it as needed, and print it to standard output.
+
+Specmatic reads the contract from standard output and proceeds from there onward as normal.
+
+Here's a sample of what the load.py file could look like.
+
+```python
+```

documentation/specmatic_json.md

@@ -13,6 +13,7 @@ Format of specmatic.json
     - [Declare contracts](#declare-contracts)
     - [Declare pipeline details](#declare-pipeline-details)
     - [Declare environment configuration](#declare-environment-configuration)
+    - [Hooks](#hooks)
 
 ### Sample specmatic.json
 
@@ -52,6 +53,10 @@ Format of specmatic.json
         "password": "PaSsWoRd"
       }
     }
+  },
+
+  "hooks": {
+    "hook_name": "command"
   }
 }
 ```
@@ -150,3 +155,16 @@ The environments key in this example contains configuration for the `staging` en
 Each environment configuration can contain
 - `baseurls` - needed when running contracts as test as part of [authentication](documentation/../authentication.html)
 - `variables` - these values are plugged into the Examples rows of an auth contract for [authentication](documentation/../authentication.html), or even when running regular contract tests
+
+### Hooks
+
+A hook is simply a command that can run on the Terminal or Command Prompt.
+
+```json
+  "hooks": {
+    "stub_load_contract": "python load.py"
+  }
+```
+
+In the above snippet, `stub_load_contract` is the hook name. "python load.py" runs and is passed the contract file name just before a contract is loaded. The hook can modify the contract and post it to standard output.
+