From 973b9d76eff855b806ec31d2c234623d0f122798 Mon Sep 17 00:00:00 2001
From: apidesigner <z@goodapi.co>
Date: Tue, 14 Feb 2017 17:09:53 +0000
Subject: [PATCH] Updates message/foreign-key-relations.md

Auto commit by GitBook Editor
---
 SUMMARY.md                       |  1 +
 message/foreign-key-relations.md | 66 ++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 message/foreign-key-relations.md

diff --git a/SUMMARY.md b/SUMMARY.md
index 80ce8d3..7dc9b54 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -25,6 +25,7 @@
   * [Content Negotiation](message/content-negotiation.md)
   * [HAL](message/hal.md)
   * [Problem Detail](message/error-reporting.md)
+  * [Foreign Key Relations](message/foreign-key-relations.md)
 * [Application](application/README.md)
 * [Evolution](evolution/README.md)
   * [Naming Conventions](evolution/naming-conventions.md)
diff --git a/message/foreign-key-relations.md b/message/foreign-key-relations.md
new file mode 100644
index 0000000..97bf91c
--- /dev/null
+++ b/message/foreign-key-relations.md
@@ -0,0 +1,66 @@
+# Foreign Key Relations
+
+## Link or Embed Foreign Key Relation
+When a resource representation includes relation with another (foreign) resource the relation **MUST** be expressed as a link relation or embed the related resource.
+
+#### Example 
+Use e.g.:
+
+```json
+{
+  "_links": {
+    "author": { "href": "/users/john" }
+    ...
+  }
+  ...
+}
+```
+
+or e.g.:
+
+```json
+{
+  ...
+  "_embedded": {
+    "author": {
+      "_links": { "self": "/users/john" },
+      "name": "John Appleseed",
+      "email": "john@apple.com"
+    }
+  }
+}
+```
+
+instead e.g.:
+
+```json
+{
+  ...
+  "author_href": "/users/john"
+}
+```
+
+## Nest Foreign Key Relation
+If a foreign object has another identifier but URI or the foreign object isn't a resource the object **MUST** be nested.
+
+#### Example
+Use e.g.:
+
+```json
+{
+  "author": {
+    "id": "1234",
+    "name": "John Appleseed",
+    "email": "john@apple.com"    
+  }
+}
+```
+
+instead e.g.:
+
+```json
+{
+  "author_id": "1234"
+}
+```
+