diff --git a/.gitignore b/.gitignore
index 7f17330b..df92a1b7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@
#assety stuff
public/assets
public/metamaps_mobile
+public/api/index.html
vendor/
node_modules
npm-debug.log
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..1170945f 100644
--- a/app/controllers/api/v2/tokens_controller.rb
+++ b/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
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/bin/build-apidocs.sh b/bin/build-apidocs.sh
new file mode 100755
index 00000000..677bbffd
--- /dev/null
+++ b/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
diff --git a/doc/api/api.raml b/doc/api/api.raml
index d61e66ac..e59ae8d3 100644
--- a/doc/api/api.raml
+++ b/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:
- 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, password, client_credentials, implicit, refresh_token ]
+ oauth_2_0: !include securitySchemes/oauth_2_0.raml
+securedBy: [ oauth_2_0 ]
traits:
- - pageable: !include traits/pageable.raml
- - orderable: !include traits/orderable.raml
- - searchable: !include traits/searchable.raml
+ pageable: !include traits/pageable.raml
+ embeddable: !include traits/embeddable.raml
+ orderable: !include traits/orderable.raml
+ searchable: !include traits/searchable.raml
schemas:
- - topic: !include schemas/_topic.json
- - synapse: !include schemas/_synapse.json
- - map: !include schemas/_map.json
- - mapping: !include schemas/_mapping.json
- - token: !include schemas/_token.json
+ topic: !include schemas/_topic.json
+ synapse: !include schemas/_synapse.json
+ map: !include schemas/_map.json
+ mapping: !include schemas/_mapping.json
+ token: !include schemas/_token.json
-resourceTypes:
- - base: !include resourceTypes/base.raml
- - item: !include resourceTypes/item.raml
- - collection: !include resourceTypes/collection.raml
+#resourceTypes:
+# base: !include resourceTypes/base.raml
+# item: !include resourceTypes/item.raml
+# collection: !include resourceTypes/collection.raml
/topics: !include apis/topics.raml
/synapses: !include apis/synapses.raml
diff --git a/doc/api/apis/mappings.raml b/doc/api/apis/mappings.raml
index 8b72b4df..a1643c86 100644
--- a/doc/api/apis/mappings.raml
+++ b/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:
diff --git a/doc/api/apis/maps.raml b/doc/api/apis/maps.raml
index c5499a33..b742adce 100644
--- a/doc/api/apis/maps.raml
+++ b/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:
diff --git a/doc/api/apis/synapses.raml b/doc/api/apis/synapses.raml
index 3169c712..dabcdad7 100644
--- a/doc/api/apis/synapses.raml
+++ b/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: |
+ from-to
or both
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: |
+ from-to
or both
+ 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: |
+ from-to
or both
+ 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:
diff --git a/doc/api/apis/tokens.raml b/doc/api/apis/tokens.raml
index 9f471615..ef7a8379 100644
--- a/doc/api/apis/tokens.raml
+++ b/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:
diff --git a/doc/api/apis/topics.raml b/doc/api/apis/topics.raml
index 7c214dd2..15b94da4 100644
--- a/doc/api/apis/topics.raml
+++ b/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:
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/resourceTypes/collection.raml b/doc/api/resourceTypes/collection.raml
index d54e6c0c..e2710dae 100644
--- a/doc/api/resourceTypes/collection.raml
+++ b/doc/api/resourceTypes/collection.raml
@@ -16,7 +16,7 @@ get?:
post?:
description: Create a new <>
responses:
- 200:
+ 201:
body:
application/json:
schema: <>
diff --git a/doc/api/resourceTypes/item.raml b/doc/api/resourceTypes/item.raml
index 1abf040e..5c227d61 100644
--- a/doc/api/resourceTypes/item.raml
+++ b/doc/api/resourceTypes/item.raml
@@ -1,3 +1,4 @@
+type: base
get?:
description: Get a <>
responses:
@@ -26,4 +27,3 @@ delete?:
responses:
204:
description: Removed
-type: base
diff --git a/doc/api/schemas/_page.json b/doc/api/schemas/_page.json
index 635f0286..47f69d95 100644
--- a/doc/api/schemas/_page.json
+++ b/doc/api/schemas/_page.json
@@ -35,4 +35,3 @@
"per"
]
}
-
diff --git a/doc/api/schemas/error.json b/doc/api/schemas/error.json
new file mode 100644
index 00000000..0967ef42
--- /dev/null
+++ b/doc/api/schemas/error.json
@@ -0,0 +1 @@
+{}
diff --git a/doc/api/securitySchemes/oauth_2_0.raml b/doc/api/securitySchemes/oauth_2_0.raml
new file mode 100644
index 00000000..b271e03a
--- /dev/null
+++ b/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 ]
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 field_id
or field_ids
column. For instance, ?embed=user
would remove the user_id
integer field from a response and replace it with a user
object field.
+
+ Possible embeddable fields are: << embedFields >>
+ required: false
+ type: string
diff --git a/doc/api/traits/orderable.raml b/doc/api/traits/orderable.raml
index 708736ab..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 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
diff --git a/doc/api/traits/pageable.raml b/doc/api/traits/pageable.raml
index 88165861..cfb6810d 100644
--- a/doc/api/traits/pageable.raml
+++ b/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
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 "example"
will be passed to SQL as LIKE %example%
. The searchable columns are: << searchFields >>
+ required: false
type: string
diff --git a/doc/production/first-deploy.md b/doc/production/first-deploy.md
index cc3a1f4a..b118a2b5 100644
--- a/doc/production/first-deploy.md
+++ b/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
diff --git a/doc/production/pull-changes.md b/doc/production/pull-changes.md
index 30f41cf5..1bd1ebbe 100644
--- a/doc/production/pull-changes.md
+++ b/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 .
diff --git a/package.json b/package.json
index 106294fd..751ef284 100644
--- a/package.json
+++ b/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",