make raml traits work and be accurate/useful

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

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

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

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
 

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:

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:

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:

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:

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:

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",

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",

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

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

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

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