Permalink
Browse files

Update doc gems & add post search

  • Loading branch information...
1 parent 5d48ee8 commit 5b5030ef0367f8883041ffb8ddca847afc15316b @berg berg committed Jul 25, 2013
View
3 .ackrc
@@ -0,0 +1,3 @@
+--ignore-dir=.git
+--ignore-dir=tmp
+--ignore-dir=output
View
10 Gemfile
@@ -1,15 +1,17 @@
source "https://rubygems.org"
-gem 'nanoc', '3.6.2'
+gem 'nanoc', '3.6.4'
gem 'adsf', '1.1.1'
gem 'fssm', '0.2.10'
-gem 'kramdown', '1.0.1'
+gem 'kramdown', '1.1.0'
gem 'coderay', '1.0.9'
-gem 'pygments.rb', '0.4.2'
+gem 'pygments.rb', '0.5.2'
gem 'nokogiri', '1.5.9'
gem 'rack', '1.5.2'
gem 'colored', '1.2'
gem 'cri', '2.3.0'
gem 'posix-spawn', '0.3.6'
gem 'yajl-ruby', '1.1.0'
-
+gem 'listen', '1.2.2'
+gem 'guard-nanoc', '1.0.1'
+gem 'rb-readline'
View
@@ -0,0 +1,8 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'nanoc' do
+ watch('nanoc.yaml') # Change this to config.yaml if you use the old config file name
+ watch('Rules')
+ watch(%r{^(content|layouts|lib)/.*$})
+end
@@ -228,25 +228,25 @@ Returns a list of Places sorted by distance or distance/string match if `q` is p
<%= endpoint "GET", "places/search", "User" %>
-<%= query_params_typed [
+<%= query_params_typed 'Query String Parameters', [
- ["latitude", "decimal", "Latitude of search location. Combined with longitude to create central point of search results."],
+ ["latitude", :required, "decimal", "Latitude of search location. Combined with longitude to create central point of search results."],
- ["longitude", "decimal", "Longitude of search location. Combined with latitude to create central point of search results."],
+ ["longitude", :required, "decimal", "Longitude of search location. Combined with latitude to create central point of search results."],
- ["q", "string", "(Optional) The name-based search query. Can be a partial string — for example, 'cre' will find any local 'creameries' and 'ice cream' locations."],
+ ["q", :optional, "string", "The name-based search query. Can be a partial string — for example, 'cre' will find any local 'creameries' and 'ice cream' locations."],
- ["radius", "decimal", "(Optional) Approximate radius (in meters) of bounding circle on results. For example, supplying <code>radius=100</code> will limit all locations to be within 100 meters. Defaults to 100, ranges between 0.001 and 50,000."],
+ ["radius", :optional, "decimal", "Approximate radius (in meters) of bounding circle on results. For example, supplying <code>radius=100</code> will limit all locations to be within 100 meters. Defaults to 100, ranges between 0.001 and 50,000."],
- ["count", "int", "(Optional) Number of results to return. Defaults to 20, ranges between 1 and 100."],
+ ["count", :optional, "integer", "Number of results to return. Defaults to 20, ranges between 1 and 100."],
- ["remove_closed", "int (0 or 1)", "(Optional) Set to 0 if you would like the result to include entities which are closed (is_closed=1) or 1 if you would only prefer to see results for entities that are open. Defaults to 1."],
+ ["remove_closed", :optional, "int (0 or 1)", "Set to 0 if you would like the result to include entities which are closed (is_closed=1) or 1 if you would only prefer to see results for entities that are open. Defaults to 1."],
- ["altitude", "decimal", "(Optional) Altitude of search location (in meters). <em>Not presently used to generate search results but may be later.</em>"],
+ ["altitude", :optional, "decimal", "Altitude of search location (in meters). <em>Not presently used to generate search results but may be later.</em>"],
- ["horizontal_accuracy", "decimal", "(Optional) Accuracy of <code>latitude</code>/<code>longitude</code> parameters (in meters). <em>Not presently used to generate search results but may be later.</em>"],
+ ["horizontal_accuracy", :optional, "decimal", "Accuracy of <code>latitude</code>/<code>longitude</code> parameters (in meters). <em>Not presently used to generate search results but may be later.</em>"],
- ["vertical_accuracy", "decimal", "(Optional) Accuracy of <code>altitude</code> parameter (in meters). <em>Not presently used to generate search results but may be later.</em>"]
+ ["vertical_accuracy", :optional, "decimal", "Accuracy of <code>altitude</code> parameter (in meters). <em>Not presently used to generate search results but may be later.</em>"]
]%>
@@ -0,0 +1,123 @@
+---
+title: "Post Search"
+---
+
+# Search
+
+* TOC
+{:toc}
+
+## Search for Posts
+
+Returns [Post](/docs/resources/post/) objects which match a given search query. Searches require an ordering and at least one search query to be specified, and allow for zero or more filters to be added. All parameters should be passed in the query string.
+
+<%= general_params_note_for "post" %> Note: Pagination is currently only available for the `id` ordering. All queries and filters are combined with an AND operation. Query parameters (not filter parameters) can use <em>"quoted strings"</em> for phrases, search syntax like <em>+foo -bar</em> and <em>foo OR baz</em> for boolean queries. Machine-only posts are not included in the search index.
+
+<%= endpoint "GET", "posts/search", "None" %>
+
+<%= query_params_typed 'General Parameters', [
+
+ ["index", :optional, "string", "Type of index to use. The default (and currently, the only) index is <code>complete</code>, which searches all posts. <em>We may add additional index types later (e.g., an index only of recent posts, for speed.)</em>"],
+
+ ["order", :optional, "string", "One of: <code>id</code>, <code>score</code>. Searches of ordering <code>id</code> are returned in roughly the same order as other streams, and support pagination. Searches of ordering <code>score</code> are returned by a relevance score. Currently, the only ordering that supports pagination is <code>id</code>, and we are working on improving relevance scores."],
+
+]%>
+
+<%= query_params_typed 'Search Query Parameters', [
+
+ ["query", :optional, "string", "Automatically attempts to extract hashtags and mentions while searching text. If you do not want this behavior, you can use more specific parameters below."],
+
+ ["text", :optional, "string", "Include posts containing certain text."],
+ ["hashtags", :optional, "string", "Include posts tagged with certain hashtags"],
+ ["links", :optional, "string", "Include posts linking to certain URLs"],
+ ["link_domains", :optional, "string", "Include posts linking to certain domains. Do not include \"www.\""],
+ ["mentions", :optional, "string", "Include posts mentioning certain users, by username. Do not include @"],
+ ["leading_mentions", :optional, "string", "Include posts directed at users, by username. Do not include @"],
+
+]%>
+
+<%= query_params_typed 'Filter Parameters', [
+ ["annotation_types", :optional, "string", "Only include posts with a specific annotation type, e.g., <code>net.app.core.fallback_url</code>"],
+ ["attachment_types", :optional, "string", "Only include posts with a specific file type attached via the <code>net.app.core.file_list</code> annotation"],
+ ["crosspost_url", :optional, "string", "Only include posts which are crossposts of a specific URL, via the <code>net.app.core.crosspost</code> annotation"],
+ ["crosspost_domain", :optional, "string", "Similar to <code>crosspost_url</code>, but only match on the host portion of the URL. Do not include \"www.\""],
+ ["place_id", :optional, "string", "Only include posts which are check-ins at a specific place, via the <code>net.app.core.checkin</code> annotation"],
+
+ ["is_reply", :optional, "int (0 or 1)", "Only include replies"],
+ ["is_directed", :optional, "int (0 or 1)", "Only include posts with leading mentions, i.e., posts which were directed at other users"],
+ ["has_location", :optional, "int (0 or 1)", "Only include posts containing geo coordinates, i.e., tagged with the <code>net.app.core.location</code> annotation"],
+ ["has_checkin", :optional, "int (0 or 1)", "Only include posts containing place IDs, i.e., tagged with the <code>net.app.core.checkin</code> annotation"],
+ ["is_crosspost", :optional, "int (0 or 1)", "Only include posts which are crossposts, i.e., tagged with the <code>net.app.core.crosspost</code> annotation"],
+ ["has_attachment", :optional, "int (0 or 1)", "Only include posts with file attachments"],
+ ["has_oembed_photo", :optional, "int (0 or 1)", "Only include posts with photo oembed annotations"],
+ ["has_oembed_video", :optional, "int (0 or 1)", "Only include posts with video (not html5video) oembed annotations"],
+ ["has_oembed_html5video", :optional, "int (0 or 1)", "Only include posts with html5video oembed annotations"],
+ ["has_oembed_rich", :optional, "int (0 or 1)", "Only include posts with rich oembed anntations"],
+
+ ["language", :optional, "string", "Only include posts with a certain language tagged with the <code>net.app.core.language</code> annotation."],
+ ["client_id", :optional, "string", "Only include posts created by a certain app. Use the alphanumeric client_id"],
+ ["creator_id", :optional, "string", "Only include posts created by a specific user. Use the user ID, not the username"],
+ ["reply_to", :optional, "string", "Only include immediate replies to a given post ID"],
+ ["thread_id", :optional, "string", "Only include posts on a specific thread"],
+
+]%>
+
+#### Example
+
+> GET https://alpha-api.app.net/stream/0/posts/search?hashtags=newsocialnetwork&mentions=berg&is_directed=1&count=-1
+
+~~~ js
+{
+ "data": [
+ ...
+ {
+ "id": "1", // note this is a string
+ "user": {
+ ...
+ },
+ "created_at": "2012-07-16T17:25:47Z",
+ "text": "@berg FIRST post on this new site #newsocialnetwork",
+ "html": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
+ "source": {
+ "client_id": "udxGzAVBdXwGtkHmvswR5MbMEeVnq6n4",
+ "name": "Clientastic for iOS",
+ "link": "http://app.net"
+ },
+ "machine_only": false,
+ "reply_to": null,
+ "thread_id": "1",
+ "num_replies": 3,
+ "num_reposts": 0,
+ "num_stars": 0,
+ "entities": {
+ "mentions": [{
+ "name": "berg",
+ "id": "2",
+ "pos": 0,
+ "len": 5
+ }],
+ "hashtags": [{
+ "name": "newsocialnetwork",
+ "pos": 34,
+ "len": 17
+ }],
+ "links": [{
+ "text": "this new site",
+ "url": "https://join.app.net"
+ "pos": 20,
+ "len": 13
+ }]
+ },
+ "you_reposted": false,
+ "you_starred": false
+ },
+ ],
+ "meta": {
+ "code": 200,
+ "max_id": "33",
+ "min_id": "1",
+ "more": true
+ }
+}
+~~~
+
View
@@ -5,7 +5,7 @@
<title><%= @item[:title] %> - App.net API Documentation</title>
- <script type="text/javascript" src='https://account.<%= env_var('LANAI_HOSTNAME') %>/exports/base/?hostname=<%= env_var('LOCAL_HOSTNAME') %>'></script>
+ <script type="text/javascript" src='https://account.<%= lanai_hostname() %>/exports/base/?hostname=<%= local_hostname() %>'></script>
<link href='https://fonts.googleapis.com/css?family=Montserrat' rel='stylesheet' type='text/css'>
<link rel="stylesheet" type="text/css" href="/assets/css/style.css">
@@ -91,6 +91,7 @@
<li><a href="/docs/resources/post/reposts/">Reposts</a></li>
<li><a href="/docs/resources/post/stars/">Stars</a></li>
<li><a href="/docs/resources/post/report/">Report</a></li>
+ <li><a href="/docs/resources/post/search/">Search</a></li>
</ul>
<li><a href="/docs/resources/channel/">Channel</a></li>
<ul class="nav nav-list">
@@ -110,5 +110,11 @@
<td>/stream/0/posts/{post_id}/report</td>
<td>User</td>
</tr>
+ <tr>
+ <td><a href="/docs/resources/post/search/#search-for-posts">Search for Posts</a></td>
+ <td>GET</td>
+ <td>/stream/0/posts/search</td>
+ <td>None</td>
+ </tr>
</tbody>
</table>
@@ -1,20 +1,22 @@
#### <%= header %>
-<table style="width: auto">
+<table class="table table-striped">
<thead>
<tr>
<th>Name</th>
- <th>Type</th>
+ <th>Required?</th>
+ <th width="50">Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<% params.each do |param| %>
<tr>
<td><code><%= param[0] %></code></td>
- <td><%= param[1] %></td>
+ <td><%= param[1].to_s.capitalize %></td>
<td><%= param[2] %></td>
+ <td><%= param[3] %></td>
</tr>
<% end %>
</tbody>
-</table>
+</table>
View
@@ -30,8 +30,8 @@ def query_params(params = [])
render '/partials/parameters', :header => "Query String Parameters", :params => params
end
-def query_params_typed(params = [])
- render "/partials/parameters-typed", :header => "Query String Parameters", :params => params
+def query_params_typed(header = "Query String Parameters", params = [])
+ render "/partials/parameters-typed", :header => header, :params => params
end
def post_params(params = [])
@@ -47,9 +47,14 @@ def pagination_note()
end
def general_params_note_for(type)
- '<em>This endpoint responds to <a href="/docs/resources/'+type+'/#general-parameters">general '+type.capitalize+' parameters</a>.</em>'
+ '<em>This endpoint responds to <a href="/docs/resources/'+type+'/#general-parameters">general '+type.capitalize+' parameters</a>.</em>'
end
-def env_var(name)
- ENV[name]
-end
+# feel free to override these from your environment
+def lanai_hostname()
+ ENV['LANAI_HOSTNAME'] || 'app.net'
+end
+
+def local_hostname()
+ ENV['LOCAL_HOSTNAME'] || 'localhost'
+end

0 comments on commit 5b5030e

Please sign in to comment.