From 7341ae087cf57672e21662b4dba9a22f83275bde Mon Sep 17 00:00:00 2001
From: John Anderson <lampwins@gmail.com>
Date: Mon, 22 Jan 2018 10:43:19 -0500
Subject: [PATCH] added statement and exaple for using ForeignKey ID's in write
 actions

---
 docs/api/examples.md | 27 ++++++++++++++++++++++++++-
 docs/api/overview.md |  2 +-
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/docs/api/examples.md b/docs/api/examples.md
index 4ec2f0f33..1fe60707a 100644
--- a/docs/api/examples.md
+++ b/docs/api/examples.md
@@ -90,7 +90,7 @@ $ curl -X POST -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0
     "id": 16,
     "name": "My New Site",
     "slug": "my-new-site",
-    "region": null,
+    "region": 5,
     "tenant": null,
     "facility": "",
     "asn": null,
@@ -102,6 +102,31 @@ $ curl -X POST -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0
     "comments": ""
 }
 ```
+Note that in this example we are creating a site bound to a region with the ID of 5. For write api actions (`POST`, `PUT`, and `PATCH`) the integer ID value is for `ForeignKey` (related model) relationships, instead of the nested representation that is used in the `GET` action.
+
+### Creating a new site with an existing region
+
+Send a `POST` rquest as before to the site list endpoint, but this time include a value for an existing region.
+
+```
+$ curl -X POST -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0" -H "Content-Type: application/json" -H "Accept: application/json; indent=4" http://localhost:8000/api/dcim/sites/ --data '{"name": "My New Site", "slug": "my-new-site"}'
+{
+    "id": 16,
+    "name": "My New Site",
+    "slug": "my-new-site",
+    "region": 5,
+    "tenant": null,
+    "facility": "",
+    "asn": null,
+    "physical_address": "",
+    "shipping_address": "",
+    "contact_name": "",
+    "contact_phone": "",
+    "contact_email": "",
+    "comments": ""
+}
+```
+Note that in this example we are creating a site bound to a region with the ID of 5. For write api actions (`POST`, `PUT`, and `PATCH`) the integer ID value is used for `ForeignKey` (related model) relationships, instead of the nested representation that is used in the `GET` (list) action.
 
 ### Modify an existing site
 
diff --git a/docs/api/overview.md b/docs/api/overview.md
index db9c1de4d..ba7e11bbf 100644
--- a/docs/api/overview.md
+++ b/docs/api/overview.md
@@ -104,7 +104,7 @@ The base serializer is used to represent the default view of a model. This inclu
 }
 ```
 
-Related objects (e.g. `ForeignKey` fields) are represented using a nested serializer. A nested serializer provides a minimal representation of an object, including only its URL and enough information to construct its name.
+Related objects (e.g. `ForeignKey` fields) are represented using a nested serializer. A nested serializer provides a minimal representation of an object, including only its URL and enough information to construct its name. When performing write api actions (`POST`, `PUT`, and `PATCH`), any `ForeignKey` relationships do not use the nested serializer, instead you will pass just the integer ID of the related model.  
 
 When a base serializer includes one or more nested serializers, the hierarchical structure precludes it from being used for write operations. Thus, a flat representation of an object may be provided using a writable serializer. This serializer includes only raw database values and is not typically used for retrieval, except as part of the response to the creation or updating of an object.