Merge pull request #714 from metamaps/feature/raml-1.0

update raml and create a build script for it

.gitignore

@@ -7,6 +7,7 @@
 #assety stuff
 public/assets
 public/metamaps_mobile
+public/api/index.html
 vendor/
 node_modules
 npm-debug.log

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,23 @@
 module Api
   module V2
     class TokensController < RestfulController
+      def searchable_columns
+        [:description]
+      end
+
+      def create
+        if params[:token].blank?
+          self.resource = resource_class.new
+        else
+          instantiate_resource
+        end
+
+        resource.user = current_user if current_user.present?
+        authorize resource
+        create_action
+        respond_with_resource
+      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

bin/build-apidocs.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# Note: you need to run `npm install` before using this script or raml2html won't be installed
+
+./node_modules/.bin/raml2html -i ./doc/api/api.raml -o ./public/api/index.html

doc/api/api.raml

@@ -2,35 +2,30 @@
 ---
 title: Metamaps
 version: v2
-baseUri: http://metamaps.cc/api/v2
+baseUri: https://metamaps.cc/api/v2
 mediaType: application/json
 
 securitySchemes:
-  - oauth_2_0:
+  oauth_2_0: !include securitySchemes/oauth_2_0.raml
-      description: |
+securedBy: [ oauth_2_0 ]
-        OAuth 2.0 implementation
-      type: OAuth 2.0
-      settings:
-        authorizationUri: https://metamaps.cc/api/v2/oauth/authorize
-        accessTokenUri: https://metamaps.cc/api/v2/oauth/token
-        authorizationGrants: [ authorization_code, password, client_credentials, implicit, refresh_token ]
 
 traits:
-  - pageable: !include traits/pageable.raml
+  pageable: !include traits/pageable.raml
-  - orderable: !include traits/orderable.raml
+  embeddable: !include traits/embeddable.raml
-  - searchable: !include traits/searchable.raml
+  orderable: !include traits/orderable.raml
+  searchable: !include traits/searchable.raml
 
 schemas:
-  - topic: !include schemas/_topic.json
+  topic: !include schemas/_topic.json
-  - synapse: !include schemas/_synapse.json
+  synapse: !include schemas/_synapse.json
-  - map: !include schemas/_map.json
+  map: !include schemas/_map.json
-  - mapping: !include schemas/_mapping.json
+  mapping: !include schemas/_mapping.json
-  - token: !include schemas/_token.json
+  token: !include schemas/_token.json
 
-resourceTypes:
+#resourceTypes:
-  - base: !include resourceTypes/base.raml
+#  base: !include resourceTypes/base.raml
-  - item: !include resourceTypes/item.raml
+#  item: !include resourceTypes/item.raml
-  - collection: !include resourceTypes/collection.raml
+#  collection: !include resourceTypes/collection.raml
 
 /topics: !include apis/topics.raml
 /synapses: !include apis/synapses.raml

doc/api/apis/mappings.raml

@@ -1,5 +1,6 @@
-type: collection
+#type: collection
 get:
+  is: [ embeddable: { embedFields: "user,map" }, orderable, pageable ]
   responses:
     200:
       body:
@@ -16,17 +17,20 @@ post:
         map_id:
           description: id of the map
         xloc:
-          description: (for Topic mappings only) x location on the canvas
+          description: (only for Topic mappings) x location on the canvas
+          required: false
         yloc:
-          description: (for Topic mappings only) y location on the canvas
+          description: (only for Topic mappings) y location on the canvas
+          required: false
   responses:
     201:
       body:
         application/json:
           example: !include ../examples/mapping.json
 /{id}:
-  type: item
+  #type: item
   get:
+    is: [ embeddable: { embedFields: "user,map" } ]
     responses:
       200:
         body:
@@ -38,10 +42,20 @@ post:
         properties:
           mappable_id:
             description: id of the topic/synapse to be mapped
+            required: false
           mappable_type:
             description: Topic or Synapse
+            required: false
           map_id:
             description: id of the map
+            required: false
+          xloc:
+            description: (only for Topic mappings) x location on the canvas
+            required: false
+          yloc:
+            description: (only for Topic mappings) y location on the canvas
+            required: false
+
     responses:
       200:
         body:
@@ -53,10 +67,19 @@ post:
         properties:
           mappable_id:
             description: id of the topic/synapse to be mapped
+            required: false
           mappable_type:
             description: Topic or Synapse
+            required: false
           map_id:
             description: id of the map
+            required: false
+          xloc:
+            description: (only for Topic mappings) x location on the canvas
+            required: false
+          yloc:
+            description: (only for Topic mappings) y location on the canvas
+            required: false
     responses:
       200:
         body:

doc/api/apis/maps.raml

@@ -1,5 +1,6 @@
-type: collection
+#type: collection
 get:
+  is: [ searchable: { searchFields: "name, desc" }, embeddable: { embedFields: "user,topics,synapses,mappings,contributors,collaborators" }, orderable, pageable ]
   responses:
     200:
       body:
@@ -27,8 +28,9 @@ post:
         application/json:
           example: !include ../examples/map.json
 /{id}:
-  type: item
+  #type: item
   get:
+    is: [ embeddable: { embedFields: "user,topics,synapses,mappings,contributors,collaborators" } ]
     responses:
       200:
         body:
@@ -40,16 +42,22 @@ post:
         properties:
           name:
             description: name
+            required: false
           desc:
             description: description
+            required: false
           permission:
             description: commons, public, or private
+            required: false
           screenshot:
             description: url to a screenshot of the map
+            required: false
           contributor_ids:
             description: the topic being linked from
+            required: false
           collaborator_ids:
             description: the topic being linked to
+            required: false
     responses:
       200:
         body:
@@ -61,16 +69,22 @@ post:
         properties:
           name:
             description: name
+            required: false
           desc:
             description: description
+            required: false
           permission:
             description: commons, public, or private
+            required: false
           screenshot:
             description: url to a screenshot of the map
+            required: false
           contributor_ids:
             description: the topic being linked from
+            required: false
           collaborator_ids:
             description: the topic being linked to
+            required: false
     responses:
       200:
         body:

doc/api/apis/synapses.raml

@@ -1,5 +1,6 @@
-type: collection
+#type: collection
 get:
+  is: [ searchable: { searchFields: "desc" }, embeddable: { embedFields: "topic1,topic2,user" }, orderable, pageable ]
   responses:
     200:
       body:
@@ -10,9 +11,11 @@ post:
     application/json:
       properties:
         desc:
-          description: name
+          description: text description of this synapse
+          required: false
         category:
-          description: from to or both
+          description: |
+            <code>from-to</code> or <code>both</code>
         permission:
           description: commons, public, or private
         topic1_id:
@@ -27,8 +30,9 @@ post:
         application/json:
           example: !include ../examples/synapse.json
 /{id}:
-  type: item
+  #type: item
   get:
+    is: [ embeddable: { embedFields: "topic1,topic2,user" } ]
     responses:
       200:
         body:
@@ -39,17 +43,24 @@ post:
       application/json:
         properties:
           desc:
-            description: name
+            description: text description of this synapse
+            required: false
           category:
-            description: from-to or both
+            description: |
+              <code>from-to</code> or <code>both</code>
+            required: false
           permission:
             description: commons, public, or private
+            required: false
           topic1_id:
             description: the topic being linked from
+            required: false
           topic2_id:
             description: the topic being linked to
+            required: false
           user_id:
             description: the creator of the topic
+            required: false
     responses:
       200:
         body:
@@ -60,17 +71,24 @@ post:
       application/json:
         properties:
           desc:
-            description: name
+            description: text description of this synapse
+            required: false
           category:
-            description: from-to or both
+            description: |
+              <code>from-to</code> or <code>both</code>
+            required: false
           permission:
             description: commons, public, or private
+            required: false
           topic1_id:
             description: the topic being linked from
+            required: false
           topic2_id:
             description: the topic being linked to
+            required: false
           user_id:
             description: the creator of the topic
+            required: false
     responses:
       200:
         body:

doc/api/apis/tokens.raml

@@ -1,10 +1,11 @@
-type: collection
+#type: collection
 post:
   body:
     application/json:
       properties:
         description:
           description: short string describing this token
+          required: false
   responses:
     201:
       body:
@@ -12,13 +13,14 @@ post:
           example: !include ../examples/token.json
 /my_tokens:
   get:
+    is: [ searchable: { searchFields: description }, pageable, orderable ]
     responses:
       200:
         body:
           application/json:
             example: !include ../examples/tokens.json
 /{id}:
-  type: item
+  #type: item
   delete:
     responses:
       204:

doc/api/apis/topics.raml

@@ -1,5 +1,6 @@
-type: collection
+#type: collection
 get:
+  is: [ searchable: { searchFields: "name, desc, link" }, embeddable: { embedFields: "user,metacode" }, orderable, pageable ]
   responses:
     200:
       body:
@@ -10,11 +11,12 @@ post:
     application/json:
       properties:
         name:
-          description: name
+          description: Topic name; this will be visible on the map
         desc:
-          description: description
+          description: Longer topic description visible when opening a map card
         link:
-          description: (optional) link to content on the web
+          description: embed a link to content on the web in the topic card
+          required: false
         permission:
           description: commons, public, or private
         metacode_id:
@@ -25,8 +27,9 @@ post:
         application/json:
           example: !include ../examples/topic.json
 /{id}:
-  type: item
+  #type: item
   get:
+    is: [ embeddable: { embedFields: "user,metacode" } ]
     responses:
       200:
         body:
@@ -37,13 +40,20 @@ post:
       application/json:
         properties:
           name:
-            description: name
+            description: Topic name; this will be visible on the map
+            required: false
           desc:
-            description: description
+            description: Longer topic description visible when opening a map card
+            required: false
           link:
-            description: (optional) link to content on the web
+            description: embed a link to content on the web in the topic card
+            required: false
           permission:
             description: commons, public, or private
+            required: false
+          metacode_id:
+            description: Topic's metacode
+            required: false
     responses:
       200:
         body:
@@ -54,13 +64,20 @@ post:
       application/json:
         properties:
           name:
-            description: name
+            description: Topic name; this will be visible on the map
+            required: false
           desc:
-            description: description
+            description: Longer topic description visible when opening a map card
+            required: false
           link:
-            description: (optional) link to content on the web
+            description: embed a link to content on the web in the topic card
+            required: false
           permission:
             description: commons, public, or private
+            required: false
+          metacode_id:
+            description: Topic's metacode
+            required: false
     responses:
       200:
         body:

doc/api/examples/topic.json

@@ -1,9 +1,9 @@
 {
   "data": {
     "id": 670,
-    "name": "Junto feedback and enhancements map",
+    "name": "Metamaps.cc Website",
-    "desc": "",
+    "desc": "Metamaps is a great website; check it out below!",
-    "link": "",
+    "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",
+      "name": "Metamaps.cc Website",
-      "desc": "",
+      "desc": "Metamaps is a great website; check it out below!",
-      "link": "",
+      "link": "https://metamaps.cc",
       "permission": "commons",
       "created_at": "2016-07-02T09:23:30.397Z",
       "updated_at": "2016-07-02T09:23:30.397Z",

doc/api/resourceTypes/collection.raml

@@ -16,7 +16,7 @@ get?:
 post?:
   description: Create a new <<resourcePathName | !singularize>>
   responses:
-    200:
+    201:
       body:
         application/json:
           schema: <<resourcePathName | !singularize>>

doc/api/resourceTypes/item.raml

@@ -1,3 +1,4 @@
+type: base
 get?:
   description: Get a <<resourcePathName | !singularize>>
   responses:
@@ -26,4 +27,3 @@ delete?:
   responses:
     204:
       description: Removed
-type: base

doc/api/schemas/_page.json

@@ -35,4 +35,3 @@
     "per"
   ]
 }
-

doc/api/schemas/error.json

@@ -0,0 +1 @@
+{}

doc/api/securitySchemes/oauth_2_0.raml

@@ -0,0 +1,7 @@
+description: |
+  OAuth 2.0 implementation
+type: OAuth 2.0
+settings:
+  authorizationUri: https://metamaps.cc/api/v2/oauth/authorize
+  accessTokenUri: https://metamaps.cc/api/v2/oauth/token
+  authorizationGrants: [ authorization_code, client_credentials ]

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 field to sort by, prefixed by "-" to sort descending
+    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,6 +2,10 @@ queryParameters:
   page:
     description: The page number
     type: integer
+    required: false
+    default: 1
   per:
     description: Number of records per page
     type: integer
+    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

doc/production/first-deploy.md

@@ -65,7 +65,14 @@ Run this in the metamaps directory, still as metamaps:
     sudo aptitude install nodejs npm
     sudo ln -s /usr/bin/nodejs /usr/bin/node
     npm install
-    npm run build
+
+#### Precompile assets
+
+This step depends on running npm install first; assets:precompile will run `NODE_ENV=production npm run build`, and the build-apidocs.sh script requires the raml2html npm package.
+
+    rake assets:precompile
+    rake perms:fix
+    bin/build-apidocs.sh
 
 #### Nginx and SSL
 

doc/production/pull-changes.md

@@ -26,6 +26,7 @@ Now that you have the code, run these commands:
     npm install
     rake db:migrate
     rake assets:precompile # includes `npm run build`
+    bin/build-apidocs.sh
     rake perms:fix
     passenger-config restart-app .
 

package.json

@@ -31,6 +31,7 @@
     "lodash": "4.16.1",
     "node-uuid": "1.4.7",
     "outdent": "0.2.1",
+    "raml2html": "^4.0.0-beta5",
     "react": "15.3.2",
     "react-dom": "15.3.2",
     "socket.io": "0.9.12",