From eff7b255e4d8ae56d498f9ae1edeac47631bb2f1 Mon Sep 17 00:00:00 2001
From: Ewan Jones <egcjones@gmail.com>
Date: Tue, 5 Mar 2019 09:11:29 +0900
Subject: [PATCH] adding documentation for request context

---
 README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/README.md b/README.md
index a9333975..881b3980 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,27 @@ use the `NewFailureResponseBuilder()` to add a custom `Error:` value in the
 response, or indicate that the broker should return an empty response rather
 than the error message.
 
+## Request Context
+
+When provisioning a service `brokerapi` validates the `service_id` and `plan_id`
+in the request, attaching the found instances to the request Context. These
+values can be retrieved in a `brokerapi.ServiceBroker` implementation using 
+utility methods `RetrieveServiceFromContext` and `RetrieveServicePlanFromContext`
+as shown below.
+
+```golang
+func (sb *ServiceBrokerImplementation) Provision(ctx context.Context,
+  instanceID string, details brokerapi.ProvisionDetails, asyncAllowed bool) {
+
+  service := brokerapi.RetrieveServiceFromContext(ctx)
+  if service == nil {
+    // Lookup service
+  }
+
+  // [..]
+}
+```
+
 ## Originating Identity
 
 The request context for every request contains the unparsed