API/Queries/Attributes.md

+[[_TOC_]]
+
 The **attrs** parameter is for attributes like sorting, joining and column definitions.
 
 https://metacpan.org/pod/distribution/DBIx-Class/lib/DBIx/Class/ResultSet.pm#ATTRIBUTES
@@ -5,7 +7,7 @@ https://metacpan.org/pod/distribution/DBIx-Class/lib/DBIx/Class/ResultSet.pm#ATT
 The IronAPI supports these options:
 
 - [join and prefetch](#join-and-prefetch)
-- (+)columns
+- [(+)columns](#columns)
 - (+)select
 - (+)as
 - order_by
@@ -32,9 +34,7 @@ Only references may be joined/prefetched. There are two ways to do this, dependi
 
 ## An attribute of an entity is a reference to an attribute of another entity
 
-Use the attribute name to join or prefetch it:
-
-system.entity.module is a reference to system.module.id:
+Use the attribute name to join or prefetch it - system.entity.module is a reference to system.module.id:
 
 `POST /data/sytem/entity/query`
 
@@ -46,11 +46,9 @@ system.entity.module is a reference to system.module.id:
 
 This fetches all the details of the linked module entry to each entity entry.
 
-## An attribute of an entity is being references by another attibute of a different entity
+## An attribute of an entity is being references by another attribute of a different entity
 
-Use `$model__$entity__$attribute` to join it:
-
-system.module.id is being referenced by system.entity.module:
+Use `$model__$entity__$attribute` to join it - system.module.id is being referenced by system.entity.module:
 
 `POST /data/system/module/query`
 
@@ -65,20 +63,16 @@ This fetches all entity entries for a module and lists them under the module.
 
 ## Restrictions
 
-Keys and values may not contain spaces.
+Keys and values may not contain spaces and must be found in the universe of the user.
 
 ## Examples
 
-
-
-
 Combined with query conditions:
 
 (This will get all transitions which have the instance as pre_state and whose post_state is 2)
 
-```JSON
-#/data/system/state/query
-
+`POST /data/system/state/query`
+```json
 {
     "conds" : {"system__transition__pre_state.post_state" : 2 },
     "attrs": {"prefetch" : "system__transition__pre_state"}
@@ -91,9 +85,9 @@ be used in the search condition and only specific columns may be returned.
 (select all columns from system.state and return only system.transition.name
  using system_transition_pre_state.post_state as search condition)
 
-```JSON
-#/data/system/state/query
+`POST /data/system/state/query`
 
+```json
 {
     "conds" : {"system__transition__pre_state.post_state" : 2 },
     "attrs": {
@@ -105,9 +99,8 @@ be used in the search condition and only specific columns may be returned.
 
 Joins and prefetches can be nested as deeply as needed:
 
-```JSON
-#/data/system/state/query
-
+`POST #/data/system/state/query`
+```json
 {
     "attrs": { "prefetch" : [  "modifying_client",
                              { "system__transition__pre_state" : "entity" }
@@ -120,7 +113,64 @@ More documentation on joining can be found here:
 
 <https://metacpan.org/pod/release/RIBASUSHI/DBIx-Class-0.082840/lib/DBIx/Class/Manual/Joining.pod>
 
-### Ordering
+# Columns
+
+`columns` defines which attributes should be fetched.
+
+## Restrictions
+
+Values may not contain spaces and must be present in the users universe.
+
+## Examples
+
+### columns
+Get only two columns of the base entity:
+
+`POST /data/system/entity/query`
+
+```json
+{
+  "attrs": {
+    "columns": [
+      "id",
+      "name"
+    ]
+  }
+}
+```
+
+To get only one column from a joined entity:
+
+`POST /data/system/entity/query`
+
+```json
+{
+  "attrs": {
+    "join": "module",
+    "columns": [
+      "module.name"
+    ]
+  }
+}
+```
+
+### +columns
+
+Use `+columns` to get all columns of the base table plus certain ones from joined tables:
+
+```json
+{
+  "attrs": {
+    "join": "module",
+    "+columns": [
+      "module.name"
+    ]
+  }
+}
+```
+
+
+# Ordering
 
 RESTRICTIONS: keys and values may not contain spaces.
 
@@ -147,7 +197,7 @@ More details can be found here:
 <https://metacpan.org/pod/distribution/DBIx-Class/lib/DBIx/Class/ResultSet.pm#order_by> and
 <https://metacpan.org/pod/release/ILMARI/SQL-Abstract-1.84/lib/SQL/Abstract.pm#ORDER_BY_CLAUSES>
 
-### Naming Conventions
+# Naming Conventions
 
 When referencing to a column, the name without the table prefix can be used as long as it is unique within
 the query. Otherwise, the table name (as used for joining the table) needs to be prefixed:
@@ -165,27 +215,7 @@ for joined/prefetched tables use their name as a prefix:
 }
 ```
 
-### Columns
-
-RESTRICTIONS: keys and values may not contain spaces.
-
-To get only the columns from a joined table:
-
-```JSON
-"attrs" : {
-    "join"    :"contracts__working_contract",
-    "columns" : ["contracts__working_contract.working_hours_per_week","contracts__working_contract.salary"]
-}
-```
-
-Use "+columns" to get all columns of the base table plus certain ones from joined tables:
-
-```JSON
-    "join"     : "contracts__working_contract",
-    "+columns" : ["contracts__working_contract.working_hours_per_week"]}
-```
-
-### Select and As
+# Select and As
 
 RESTRICTIONS: keys and values may not contain spaces.
 
@@ -219,7 +249,7 @@ Returns one row:
 
 <https://metacpan.org/pod/distribution/DBIx-Class/lib/DBIx/Class/ResultSet.pm#select>
 
-### Collapse
+# Collapse
 
 When "collape" is set to a true value, indicates that any rows fetched from joined has_many relationships
 are to be aggregated into the corresponding "parent" object: