Clarify resource embedding constraints (#97)

api.rst

@@ -342,7 +342,7 @@ However because a foreign key constraint exists between Films and Directors, we
 
 .. code-block:: http
 
-  GET /films?select=title,directors(last_name) HTTP/1.1
+  GET /films?select=title,directors(id,last_name) HTTP/1.1
 
 Which would return
 
@@ -351,21 +351,36 @@ Which would return
   [
     { "title": "Workers Leaving The Lumière Factory In Lyon",
       "directors": {
+        "id": 2,
         "last_name": "Lumière"
       }
     },
     { "title": "The Dickson Experimental Sound Film",
       "directors": {
+        "id": 1,
         "last_name": "Dickson"
       }
     },
     { "title": "The Haunted Castle",
       "directors": {
+        "id": 3,
         "last_name": "Méliès"
       }
     }
   ]
 
+The primary key of the table of the resource being embedded must be specified,
+either explicitly, like in the example above, or implicitly through a wildcard.
+
+In this example, since the relationship is a forward relationship, there is
+only one director associated with a film. As the table name is plural it might
+be preferable for it to be singular instead. An table name alias can accomplish
+this:
+
+.. code-block:: http
+
+  GET /films?select=title,director:directors(id,last_name) HTTP/1.1
+
 .. note::
 
   As of PostgREST v4.1, parens :code:`()` are used rather than brackets :code:`{}` for the list of embedded columns. Brackets are still supported, but are deprecated and will be removed in v5.
@@ -376,6 +391,9 @@ PostgREST can also detect relations going through join tables. Thus you can requ
 
   GET /directors?select=films(title,year) HTTP/1.1
 
+Here it is not necessary to specify the table's primary key of the embedded
+resource.
+
 .. note::
 
   Whenever foreign key relations change in the database schema you must refresh PostgREST's schema cache to allow resource embedding to work properly. See the section :ref:`schema_reloading`.