From 3d7a2ef5b1ab678b7dcbcd11060ca9d93297e4a5 Mon Sep 17 00:00:00 2001
From: Devin Howard <devin@callysto.com>
Date: Tue, 4 Oct 2016 13:51:07 +0800
Subject: [PATCH] make raml traits work and be accurate/useful

---
 app/controllers/api/v2/mappings_controller.rb | 3 +++
 app/controllers/api/v2/tokens_controller.rb   | 4 ++++
 app/controllers/api/v2/topics_controller.rb   | 3 +++
 doc/api/api.raml                              | 1 +
 doc/api/apis/mappings.raml                    | 2 ++
 doc/api/apis/maps.raml                        | 2 ++
 doc/api/apis/synapses.raml                    | 2 ++
 doc/api/apis/tokens.raml                      | 1 +
 doc/api/apis/topics.raml                      | 5 ++++-
 doc/api/examples/topic.json                   | 6 +++---
 doc/api/examples/topics.json                  | 6 +++---
 doc/api/traits/embeddable.raml                | 8 ++++++++
 doc/api/traits/orderable.raml                 | 2 ++
 doc/api/traits/pageable.raml                  | 4 +++-
 doc/api/traits/searchable.raml                | 4 +++-
 15 files changed, 44 insertions(+), 9 deletions(-)
 create mode 100644 doc/api/traits/embeddable.raml

diff --git a/app/controllers/api/v2/mappings_controller.rb b/app/controllers/api/v2/mappings_controller.rb
index 86aba865..4490e4af 100644
--- a/app/controllers/api/v2/mappings_controller.rb
+++ b/app/controllers/api/v2/mappings_controller.rb
@@ -2,6 +2,9 @@
 module Api
   module V2
     class MappingsController < RestfulController
+      def searchable_columns
+        []
+      end
     end
   end
 end
diff --git a/app/controllers/api/v2/tokens_controller.rb b/app/controllers/api/v2/tokens_controller.rb
index d1a6b255..291c33d4 100644
--- a/app/controllers/api/v2/tokens_controller.rb
+++ b/app/controllers/api/v2/tokens_controller.rb
@@ -2,6 +2,10 @@
 module Api
   module V2
     class TokensController < RestfulController
+      def searchable_columns
+        [:description]
+      end
+
       def my_tokens
         authorize resource_class
         instantiate_collection
diff --git a/app/controllers/api/v2/topics_controller.rb b/app/controllers/api/v2/topics_controller.rb
index 22e534ce..b47dc8a0 100644
--- a/app/controllers/api/v2/topics_controller.rb
+++ b/app/controllers/api/v2/topics_controller.rb
@@ -2,6 +2,9 @@
 module Api
   module V2
     class TopicsController < RestfulController
+      def searchable_columns
+        [:name, :desc, :link]
+      end
     end
   end
 end
diff --git a/doc/api/api.raml b/doc/api/api.raml
index d8a3afc3..e59ae8d3 100644
--- a/doc/api/api.raml
+++ b/doc/api/api.raml
@@ -11,6 +11,7 @@ securedBy: [ oauth_2_0 ]
 
 traits:
   pageable: !include traits/pageable.raml
+  embeddable: !include traits/embeddable.raml
   orderable: !include traits/orderable.raml
   searchable: !include traits/searchable.raml
 
diff --git a/doc/api/apis/mappings.raml b/doc/api/apis/mappings.raml
index fad67fd2..9d0be18b 100644
--- a/doc/api/apis/mappings.raml
+++ b/doc/api/apis/mappings.raml
@@ -1,5 +1,6 @@
 #type: collection
 get:
+  is: [ embeddable: { embedFields: "user,map" }, orderable, pageable ]
   responses:
     200:
       body:
@@ -27,6 +28,7 @@ post:
 /{id}:
   #type: item
   get:
+    is: [ embeddable: { embedFields: "user,map" } ]
     responses:
       200:
         body:
diff --git a/doc/api/apis/maps.raml b/doc/api/apis/maps.raml
index 8c2c2825..3cc7d13c 100644
--- a/doc/api/apis/maps.raml
+++ b/doc/api/apis/maps.raml
@@ -1,5 +1,6 @@
 #type: collection
 get:
+  is: [ searchable: { searchFields: "name, desc" }, embeddable: { embedFields: "user,topics,synapses,mappings,contributors,collaborators" }, orderable, pageable ]
   responses:
     200:
       body:
@@ -29,6 +30,7 @@ post:
 /{id}:
   #type: item
   get:
+    is: [ embeddable: { embedFields: "user,topics,synapses,mappings,contributors,collaborators" } ]
     responses:
       200:
         body:
diff --git a/doc/api/apis/synapses.raml b/doc/api/apis/synapses.raml
index 3fb1eee1..cfd2f762 100644
--- a/doc/api/apis/synapses.raml
+++ b/doc/api/apis/synapses.raml
@@ -1,5 +1,6 @@
 #type: collection
 get:
+  is: [ searchable: { searchFields: "desc" }, embeddable: { embedFields: "topic1,topic2,user" }, orderable, pageable ]
   responses:
     200:
       body:
@@ -29,6 +30,7 @@ post:
 /{id}:
   #type: item
   get:
+    is: [ embeddable: { embedFields: "topic1,topic2,user" } ]
     responses:
       200:
         body:
diff --git a/doc/api/apis/tokens.raml b/doc/api/apis/tokens.raml
index b9c3aaff..70b69765 100644
--- a/doc/api/apis/tokens.raml
+++ b/doc/api/apis/tokens.raml
@@ -12,6 +12,7 @@ post:
           example: !include ../examples/token.json
 /my_tokens:
   get:
+    is: [ searchable: { searchFields: description }, pageable, orderable ]
     responses:
       200:
         body:
diff --git a/doc/api/apis/topics.raml b/doc/api/apis/topics.raml
index 07eb8886..09706754 100644
--- a/doc/api/apis/topics.raml
+++ b/doc/api/apis/topics.raml
@@ -1,5 +1,6 @@
 #type: collection
 get:
+  is: [ searchable: { searchFields: "name, desc, link" }, embeddable: { embedFields: "user,metacode" }, orderable, pageable ]
   responses:
     200:
       body:
@@ -14,7 +15,8 @@ post:
         desc:
           description: description
         link:
-          description: (optional) link to content on the web
+          description: link to content on the web
+          required: false
         permission:
           description: commons, public, or private
         metacode_id:
@@ -27,6 +29,7 @@ post:
 /{id}:
   #type: item
   get:
+    is: [ embeddable: { embedFields: "user,metacode" } ]
     responses:
       200:
         body:
diff --git a/doc/api/examples/topic.json b/doc/api/examples/topic.json
index 90e702a2..d65eced1 100644
--- a/doc/api/examples/topic.json
+++ b/doc/api/examples/topic.json
@@ -1,9 +1,9 @@
 {
   "data": {
     "id": 670,
-    "name": "Junto feedback and enhancements map",
-    "desc": "",
-    "link": "",
+    "name": "Metamaps.cc Website",
+    "desc": "Metamaps is a great website; check it out below!",
+    "link": "https://metamaps.cc",
     "permission": "commons",
     "created_at": "2016-07-02T09:23:30.397Z",
     "updated_at": "2016-07-02T09:23:30.397Z",
diff --git a/doc/api/examples/topics.json b/doc/api/examples/topics.json
index d4eba53e..5553c9e5 100644
--- a/doc/api/examples/topics.json
+++ b/doc/api/examples/topics.json
@@ -2,9 +2,9 @@
   "data": [
     {
       "id": 670,
-      "name": "Junto feedback and enhancements map",
-      "desc": "",
-      "link": "",
+      "name": "Metamaps.cc Website",
+      "desc": "Metamaps is a great website; check it out below!",
+      "link": "https://metamaps.cc",
       "permission": "commons",
       "created_at": "2016-07-02T09:23:30.397Z",
       "updated_at": "2016-07-02T09:23:30.397Z",
diff --git a/doc/api/traits/embeddable.raml b/doc/api/traits/embeddable.raml
new file mode 100644
index 00000000..e9eb61db
--- /dev/null
+++ b/doc/api/traits/embeddable.raml
@@ -0,0 +1,8 @@
+queryParameters:
+  embed:
+    description: |
+      Comma-separated list of columns to embed. Each embedded column will be returned instead of the corresponding <code>field_id</code> or <code>field_ids</code> column. For instance, <code>?embed=user</code> would remove the <code>user_id</code> integer field from a response and replace it with a <code>user</code> object field. 
+      
+      Possible embeddable fields are: <pre><< embedFields >></pre>
+    required: false
+    type: string
diff --git a/doc/api/traits/orderable.raml b/doc/api/traits/orderable.raml
index a2b45ce9..25baa756 100644
--- a/doc/api/traits/orderable.raml
+++ b/doc/api/traits/orderable.raml
@@ -1,3 +1,5 @@
 queryParameters:
   sort:
     description: The name of the comma-separated fields to sort by, prefixed by "-" to sort descending
+    required: false
+    type: string
diff --git a/doc/api/traits/pageable.raml b/doc/api/traits/pageable.raml
index 31fcb9a8..cfb6810d 100644
--- a/doc/api/traits/pageable.raml
+++ b/doc/api/traits/pageable.raml
@@ -2,8 +2,10 @@ queryParameters:
   page:
     description: The page number
     type: integer
+    required: false
     default: 1
   per:
     description: Number of records per page
     type: integer
-    default: 20
+    required: false
+    default: 25
diff --git a/doc/api/traits/searchable.raml b/doc/api/traits/searchable.raml
index 53ae8525..fb7700a9 100644
--- a/doc/api/traits/searchable.raml
+++ b/doc/api/traits/searchable.raml
@@ -1,4 +1,6 @@
 queryParameters:
   q:
-    description: The search string to query by
+    description: |
+      Search text columns for this string. A query of <code>"example"</code> will be passed to SQL as <code>LIKE %example%</code>. The searchable columns are: <pre><< searchFields >></pre>
+    required: false
     type: string