Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

1180 lines (1082 sloc) 31.24 kB
<div class="yui-ge">
<div class="yui-u first">
<% $toc->html_for_document_body( $m->request_comp()->name() ) | n %>
</div>
<div class="yui-u toc">
<h2>Table of Contents</h2>
<% $toc->html_for_toc() | n %>
</div>
</div>
<%once>
my $toc;
</%once>
<%init>
my $docs = $m->scomp('.docs');
unless ($toc) {
$toc = Text::TOC::HTML->new();
$toc->add_file(
file => $m->request_comp()->name(),
content => $docs,
);
}
</%init>
<%def .docs>
<p>
VegGuide currently supports a read-only REST API. This API allows you to
retrieve information about entries, regions, and users using a well-defined
set of URIs. Currently, all information is returned as JSON.
</p>
<h2>API Explorer</h2>
<p>
There is an <a href="/api-explorer/">API explorer</a> app if you'd like to
learn more about the API by playing with it.
</p>
<h2>Versioning</h2>
<p>
This document describes version <strong><% $VegGuide::REST_VERSION
%></strong> of the VegGuide REST API. This version number follows
the <a href="http://semver.org/">Semantic Versioning
Specification</a>. Since the major version number is
currently <strong>0</strong>, the API is still in the experimental phase,
and may change a fair bit before it is declared stable.
</p>
<p>
A new URI endpoint is considered a minor version change. Adding an
additional key to an existing document is also a minor version
change. Removing a key or changing an the type of an existing key in a
document is a major version change. Removing a URI endpoint or changing it's
document type entirely is a major version change.
</p>
<h2>Content Types</h2>
<p>
All responses from this REST API are valid JSON documents. However, rather
than using a generic <em>application/json</em> <strong>Content-Type</strong>
header, we use a content type that specifies the data in the response.
</p>
<p>
For example, information about an entry is returned with the content
type <em style="white-space:nowrap">application/vnd.vegguide.org-entry+json;
charset=UTF-8; version=<% $VegGuide::REST_VERSION %></em>. The first part of
the content type tells you that the document contains information on a
single entry. The remainder indicates the charset and version.
</p>
<p>
In the future, the minor and patch numbers of the version may change without
warning. If we ever need to update the major version number, we will almost
certainly honor the <strong>Accept</strong> header if it requests an older
(major) version number.
</p>
<p>
Each document describes either a single resource or a collection of
resources. Typically, these resources will be regions, entries, or
users. Depending on the document type, a resource may in turn contain
information about related resources. For example, a region resource may
include information about the entries it contains, or an entry may contain
information about the user who created it.
</p>
<h2>Core Data Structures</h2>
<p>
The follow data types appear in many responses, and the documentation will
reference them rather than repeat their definitions over and over. Whenever
a data structure includes a URI, that URI will contain the full URI,
including scheme and hostname. The core data structures are always a JSON
object with a set of well-defined keys and values.
</p>
<p>
Some structures include both English data and localized data. The English
data should always be in the Latin-1 subset of Unicode. The localized data
may be in any script. In most cases, you can figure out the language of the
localized data by looking at the locale associated with the region. All
strings are in UTF-8 encoding.
</p>
<p>
If a key's value would be null, an empty string, or an empty array, it is
always omitted.
</p>
<p>
All datetimes are
returned <a href="http://tools.ietf.org/html/rfc3339">RFC3339</a>
format. Datetimes are always in the UTC time zone.
</p>
<a name="Region"></a>
<h3>Region</h3>
<p>
A region can be anything from a continent to a city. We also have some
special regions like "Internet", "Airports", or a specific airport like "MSP
- Twin Cities".
</p>
<p>
A region can contain entries, child regions, or in some rare cases, both. A
region data structure contains the following keys:
</p>
<table class="docs-table">
<thead>
<tr>
<th>Key name</th>
<th>Type</th>
<th>Description</th>
<th>Always present?</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>string</td>
<td>The name of the region in English.</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>localized_name</td>
<td>string</td>
<td>The name of the region in the region's locale, if it has one.</td>
<td></td>
</tr>
<tr>
<td>is_country</td>
<td>boolean</td>
<td>Indicates whether or not the region is a country.</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>locale</td>
<td>string</td>
<td>
A locale code like "en_CA" or "zh_TW". This is the locale for any
localized data associated with the region's entries. Elements of the
locale code are separated by underscores ("_").
</td>
<td></td>
</tr>
<tr>
<td>time_zone</td>
<td>string</td>
<td>
The name of the time zone associated with this region. This will be an
<a href="http://www.iana.org/time-zones/">IANA time zone</a> name like
"America/Chicago" or "Asia/Taipei".
</td>
<td></td>
</tr>
<tr>
<td>entry_count</td>
<td>integer&nbsp;(>=&nbsp;0)</td>
<td>
The number of entries in the region. This only include entries which
are not marked closed. Also note that this does not recurse into the
child regions for this region. This may be 0.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>uri</td>
<td>URI</td>
<td>
The canonical URI for the region. This URI always returns the full
region data structure for the given region.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>entries_uri</td>
<td>URI</td>
<td>
A URI which returns the list of entries for the region.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td colspan="4">
<strong>The following keys are only present when the data structure
includes related data.</strong>
</td>
</tr>
<tr>
<td>parent</td>
<td><a href="#Region">Region</a></td>
<td>
The region's parent region, if it has one. This is a
single <a href="#Region">Region</a> data structure without any related
data. It may not be present if the region is a top-level region.
</td>
<td></td>
</tr>
<tr>
<td>children</td>
<td>array of <a href="#Region">Regions</a></td>
<td>
An array of child regions contained in this region. For example, the
"USA" region contains the "Minnesota" and "New York" regions, among
others. The child regions are themselves Region data structures, but
they do not include any related data. This key may not be present if
the region does not have any child regions.
</td>
<td></td>
</tr>
<tr>
<td>comments</td>
<td>array of <a href="#Comment">Comments</a></td>
<td>
An array of comment data structures. Comments for a region typically
contain some information about veg eating in the region. They may also
contain references to other websites of interest for the region. See
below for details on the <a href="#Comment">Comment data
structure</a>. This key may not be present if the region does not have
any comments.
</td>
<td></td>
</tr>
</tbody>
</table>
<h3>Entry</h3>
<p>
An entry is a single place in the database, such as a restaurant or grocery.
</p>
<table class="docs-table">
<thead>
<tr>
<th>Key name</th>
<th>Type</th>
<th>Description</th>
<th>Always present?</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>string</td>
<td>The entry's name in English.</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>distance</td>
<td>string</td>
<td>
The entry's distance from a search location. This is only present when
searching for entries near a specific location. The string will
include a number and units, something like "1.3 miles".
</td>
<td>
This is always present for entries in geographical search results,
and never present otherwise.
</td>
</tr>
<tr>
<td>sortable_name</td>
<td>string</td>
<td>
The entry's name in English, but with words like "A" and "The"
removed. This is only done for English words.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>localized_name</td>
<td>string</td>
<td>The name of the entry in the language of region's locale, if it has one.</td>
<td></td>
</tr>
<tr>
<td>short_description</td>
<td>string</td>
<td>A short description of the entry.</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>localized_short_description</td>
<td>string</td>
<td>A short description in the language of the region's locale.</td>
<td></td>
</tr>
<tr>
<td>long_description</td>
<td><a href="#Formatted-Text">Formatted Text</a></td>
<td>
A longer description of the entry. This may
include <a href="#wikitext">VegGuide wikitext markup</a>.
</td>
<td></td>
</tr>
<tr>
<td>localized_long_description</td>
<td><a href="Formatted-Text">Formatted Text</a></td>
<td>
A long description in the language of the region's locale. This may
include <a href="#wikitext">VegGuide wikitext markup</a>.
</td>
<td></td>
</tr>
<tr>
<td>
address1,<br />
address2,<br />
neighborhood,<br />
city,<br />
region,<br />
postal_code
</td>
<td>string</td>
<td>
Address information for the entry. The <code>region</code> is the
entry's state or province.
</td>
<td></td>
</tr>
<tr>
<td>
localized_address1,<br />
localized_address2,<br />
localized_neighborhood,<br />
localized_city,<br />
localized_region,<br />
postal_code
</td>
<td>string</td>
<td>Localized address information for the entry.</td>
<td></td>
</tr>
<tr>
<td>directions</td>
<td>string</td>
<td>Directions to the location of the entry.</td>
<td></td>
</tr>
<tr>
<td>phone</td>
<td>string</td>
<td>
A phone number for the entry. This will not be in any specific format,
and may not always include a country prefix.
</td>
<td></td>
</tr>
<tr>
<td>website</td>
<td>URI</td>
<td>
A website for the entry. This may be a Facebook page in some cases.
</td>
<td></td>
</tr>
<tr>
<td>
veg_level,<br />
veg_level_description
</td>
<td>
integer,<br />
string
</td>
<td>
<p>
How veg-friendly the entry is, from 0-5. The levels are:
</p>
<ul>
% for my $level (0..5) {
<li><strong><% $level %></strong> - <% VegGuide::Vendor->VegLevelDescription($level) %></li>
% }
</ul>
<p>
Level 0 and level 3 are both very rare in our database.
</p>
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>price_range</td>
<td>string</td>
<td>
<p>
A description of the entry's price range. Currently these can be:
</p>
<ul>
% for my $pr ( VegGuide::PriceRange->All() ) {
<li><% $pr->description() %></li>
% }
</ul>
</td>
<td></td>
</tr>
<tr>
<td>hours</td>
<td>array of objects</td>
<td>
<p>
This key describes the entry's hours of operations. It consists of
an array of objects. Each objects has two keys, <code>days</code>
and <code>hours</code>. The <code>days</code> key contains something
like "Mon" or "Mon - Fri". The <code>hours</code> key is itself an
array of strings. Each element of the array contains a time
range. Some places close between lunch and dinner, and these have
two elements in the array. There is an example at the end of this
table.
</p>
</td>
<td></td>
</tr>
<tr>
<td>allows_smoking</td>
<td>boolean or null</td>
<td>
Indicates whether or not smoking is allows at this place. Note that
this field can be <code>null</code>, which means that we do not know
whether or not smoking is allowed.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>is_wheelchair_accessible</td>
<td>boolean or null</td>
<td>
A boolean indicating whether or not this entry is
wheelchair-accessible. This field can be <code>null</code>, which
means that we do not know whether or not it is accessible.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>accepts_reservations</td>
<td>boolean or null</td>
<td>
A boolean indicating whether or not this entry accepts
reservations. This field can be <code>null</code>, which means that we
do not know whether or not it accepts reservations.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>is_cash_only</td>
<td>boolean</td>
<td>Indicates whether or not this entry only accepts cash as payment.</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>
creation_datetime,<br />
last_modified_datetime
</td>
<td>datetime</td>
<td>
When an entry is first created, these two datetimes are the same.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>close_date</td>
<td>date</td>
<td>
This is set when an entry is no longer open. This is just a date
with a time in YYYY-MM-DD format, something like "2012-07-09".
</td>
<td></td>
</tr>
<tr>
<td>rating_count</td>
<td>integer&nbsp;(>=&nbsp;0)</td>
<td>
The number of ratings for this entry. This may be 0.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>weighted_rating</td>
<td>decimal</td>
<td>
The weighted rating for the entry. This will be a decimal number from
1 to 5. This will not be present if no one has rated the entry yet.
</td>
<td></td>
</tr>
<tr>
<td>categories</td>
<td>array of strings</td>
<td>
<p>
An array of category names for the entry. Every entry has at least
one category. The current list of categories is:
</p>
<ul>
% for my $category ( VegGuide::Category->All() ) {
<li><% $category->name() %></li>
% }
</ul>
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>cuisines</td>
<td>array of strings</td>
<td>
<p>
An array of cuisines names for the entry. These are things like
"Chinese", "Indian", or "Pizza". This only applies to some
categories of entry, and not every entry has this key set. These are
always returned in alphabetically sorted order.
</p>
</td>
<td></td>
</tr>
<tr>
<td>tags</td>
<td>array of strings</td>
<td>
<p>
An array of tags for the entry. These are things like "Large
Group-Friendly" or "Romantic". These are returned in alphabetically
sorted order.
</p>
</td>
<td></td>
</tr>
<tr>
<td>images</td>
<td>array of <a href="#Image">Images</a></td>
<td>
An array of <a href="#Image">Image data structures</a> for the
entry. Each image will include four sizes. The first three are limited
to 120x120, 250x250, and 400x620 respectively. The last will be the
image that was originally uploaded, which can be any size, and may
potentially be quite large.
</td>
<td></td>
</tr>
<tr>
<td>user</td>
<td><a href="#User">User</a></td>
<td>
A <a href="#User">User data structure</a> for the creator of this
entry. This data structure <em>does not</em> include related data.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>uri</td>
<td>URI</td>
<td>
The canonical URI for the entry. This URI always returns the full
entry data structure for the given entry.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>reviews_uri</td>
<td>URI</td>
<td>
A URI which returns the reviews and ratings for this entry.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td colspan="4">
<strong>The following keys are only present when the data structure
includes related data.</strong>
</td>
</tr>
<tr>
<td>region</td>
<td><a href="#Region">Region</a></td>
<td>
A <a href="#Region">Region</a> data structure for the creator of this
entry. This data structure <em>does not</em> include related data.
</td>
<td>&#x2714; (when related data is included)</td>
</tr>
</tbody>
</table>
<p>
Here is an example of the hours data structure:
</p>
<pre><code>[
{
days => 'Mon - Fri',
hours => ['10:30am - 2pm', '5pm - 10pm']
},
{
days => 'Sat - Sun',
hours => ['closed']
}
]</code></pre>
<a name="User"></a>
<h3>User</h3>
<table class="docs-table">
<thead>
<tr>
<th>Key name</th>
<th>Type</th>
<th>Description</th>
<th>Always present?</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>string</td>
<td>The user's username.</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>bio</td>
<td><a href="Formatted-Text">Formatted Text</a></td>
<td>
Biographical information about the user.
</td>
<td></td>
</tr>
<tr>
<td>
veg_level,<br />
veg_level_description
</td>
<td>
integer,<br />
string
</td>
<td>
<p>
How vegetarian the user is, from 0-4. The levels are:
</p>
<ul>
% for my $level (0..4) {
<li><strong><% $level %></strong> - <% VegGuide::User->VegLevelDescription($level) %></li>
% }
</ul>
</td>
<td></td>
</tr>
<tr>
<td>website</td>
<td>URI</td>
<td>
The website for the user.
</td>
<td></td>
</tr>
<tr>
<td>image</td>
<td><a href="#Image">Image</a></td>
<td>
An <a href="#Image">Image data structure</a> for the user. This will
include two sizes of image. The smaller of the two is limited to
40x40, and the larger to 100x100. The image data structure will not
include user information, since it is always the same to whom the
image belongs.
</td>
<td></td>
</tr>
<tr>
<td>uri</td>
<td>URI</td>
<td>
The canonical URI for the user. This URI always returns the full user
data structure for the given user.
</td>
<td>&#x2714;</td>
</tr>
</tbody>
</table>
<a name="Comment"></a>
<h3>Comment</h3>
<p>
Both region comments and entry reviews are returned with essentially the
same data structure, though reviews have some additional data.
</p>
<p>
Note that an entry review may contain just a body, just a rating, or both.
</p>
<table class="docs-table">
<thead>
<tr>
<th>Key name</th>
<th>Type</th>
<th>Description</th>
<th>Always present?</th>
</tr>
</thead>
<tbody>
<tr>
<td>body</td>
<td><a href="#Formatted-Text">Formatted Text</a></td>
<td>
The comment body as a <a href="#Formatted-Text">Formatted Text data
structure</a>.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>user</td>
<td><a href="#User">User</a></td>
<td>
A <a href="#User">User data structure</a> for the author of the
comment. This data structure <em>does not</em> include related data.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>
last_modified_datetime
</td>
<td>datetime</td>
<td>
When this comment was created or most recently updated.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>rating</td>
<td>integer (1-5)</td>
<td>
A rating from 1 to 5, where 1 is terrible and 5 is excellent. This is
only present for entry reviews, not region comments.
</td>
<td></td>
</tr>
</tbody>
</table>
<a name="Image"></a>
<h3>Image</h3>
<p>
An image is a single picture, usually available in multiple sizes. The image
data may include a caption, as well as information about the user who
uploaded the image.
</p>
<table class="docs-table">
<thead>
<tr>
<th>Key name</th>
<th>Type</th>
<th>Description</th>
<th>Always present?</th>
</tr>
</thead>
<tbody>
<tr>
<td>mime_type</td>
<td>string</td>
<td>
This will be one of <em>image/gif</em>, <em>image/jpeg</em>,
or <em>image/png</em>.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>caption</td>
<td>string</td>
<td>A caption for the image.</td>
<td></td>
</tr>
<tr>
<td>files</td>
<td>array of <a href="#Image-File">Image Files</a></td>
<td>
This is an array of image file structures. Each structure provides
information about an image file with a specified size. The array is
always sorted by size. The possible dimensions for each image file
depends on whether this is a user or entry image.
</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>user</td>
<td><a href="#User">User</a></td>
<td>
A <a href="#User">User data structure</a> for the creator of this
entry. This data structure <em>does not</em> include related data.
</td>
<td></td>
</tr>
</tbody>
</table>
<a name="Image-File"></a>
<h3>Image File</h3>
<p>
This data structure contains information about a specific file for an image.
</p>
<table class="docs-table">
<thead>
<tr>
<th>Key name</th>
<th>Type</th>
<th>Description</th>
<th>Always present?</th>
</tr>
</thead>
<tbody>
<tr>
<td>uri</td>
<td>URI</td>
<td>The URI for this image file.</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>height</td>
<td>positive integer</td>
<td>The height of the image.</td>
<td>&#x2714;</td>
</tr>
<tr>
<td>width</td>
<td>positive integer</td>
<td>The width of the image.</td>
<td>&#x2714;</td>
</tr>
</tbody>
</table>
<a name="Formatted-Text"></a>
<h3>Formatted Text</h3>
<p>
Some fields contain a type of wikitext which is rendered as HTML on the
website. These fields are returned as objects where the attribute names are
a MIME type and the attribute values are the text in that format. Currently,
this data structure return two MIME types, <em>text/html</em>,
and <em style="white-space:nowrap">text/vnd.vegguide.org-wikitext</em>. The
wikitext format VegGuide uses
is <a href="/site/help#wiki-formatting">described on the help page</a>.
</p>
<code><pre>
{
'text/html': '&lt;p&gt;Blah blah blah&lt;/p&gt;',
'text/vnd.vegguide.org-wikitext': 'Blah blah blah'
}
</pre></code>
<p>
In the future, the site will use Markdown internally, and the existing
wikitext format will go away. You are encouraged to use the HTML
representation if you can.
</p>
<h2>Entry Points</h2>
<p>
The VegGuide REST API defines several well known entry points. These URIs
are guaranteed to exist, and their responses will generally contain links to
other site URIs.
</p>
<p>
Many of the URIs that the site offers include a numeric id, for
example <code>/region/13</code>. You are strongly encouraged <em>not</em> to
rely on the stability of these numbers. Instead, use one of the defined
entry points to find items of interest for your applications.
</p>
<a name="Top-level"></a>
<h3>Top-Level</h3>
<ul>
<li>
<strong>URI</strong>: <% $base_uri %>
</li>
<li>
<strong>Type</strong>: application/vnd.vegguide.org-regions+json
</li>
</ul>
<p>
The top-level URI returns a document enumerating the top-level regions.
</p>
<p>
The structure of the document is as follows:
</p>
<pre><code>{
"regions": {
"primary": [ ... ],
"secondary": [ ... ]
}
}</code></pre>
<p>
The primary and secondary keys contain an array of <a href="#Region">Region
data structures</a> with related data. The primary regions are continents
and oceanic areas. The secondary regions are currently just "Internet" and
"Airports".
</p>
<a name="Geographical-Searches">
<h3>Geographical Searches</h3>
<p>
There are two different entry point URIs for geographical searches. You can
search by address or by latitude and longitude. Both URIs return the same
response.
</p>
<ul>
<li>
<strong>Address URI</strong>: <% $base_uri %>search/by-address/<code>{address}</code>
</li>
<li>
<strong>Lat/Long URI</strong>: <% $base_uri %>search/by-lat-long/<code>{latitude}</code>,<code>{longitude}</code>
</li>
<li>
<strong>Type</strong>: application/vnd.vegguide.org-entries+json
</li>
</ul>
<p>
These searches accept the following query parameters:
</p>
<table class="docs-table">
<thead>
<tr>
<th>Key name</th>
<th>Type</th>
<th>Default value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>distance</td>
<td>positive number</td>
<td>5</td>
<td>The search radius in miles or kilometers.</td>
</tr>
<tr>
<td>unit</td>
<td>enum</td>
<td>see description</td>
<td>
This can be either <code>mile</code> or <code>km</code>. If the search
is for an address in the US, this defaults to <code>mile</code>,
otherwise it defaults to <code>km</code>.
</td>
</tr>
<& .paging-param-rows &>
</tbody>
</table>
<p>
This document returns the result of a search around a specific address or
latitude and longitude.
</p>
<pre><code>{
"uri": "http://...",
"entry_count": 123,
"entries": [ ... ],
"region": { ... }
}</code></pre>
<p>
The <em>entries</em> key contains an array of <a href="#Entry">Entry data
structures</a> without related data. The entry data structures <em>will</em>
include a <em>distance</em> key. The <em>regions</em> key contains the
region associated with the nearest entry. This is a <a href="#Region">Region
data structure</a> without related data.
</p>
<p>
If you search by address and the address does not resolve to a latitude and
longitude, we return a <a href="#Not-Found">404 Not Found</a> response.
</p>
<h2>Other URIs</h2>
<p>
These URIs will show up in other data structures, so understanding their
document structures is important when coding to this API. All of these URIs
include a numeric id, and you are encouraged not to rely on these numbers
remaining stable.
</p>
<h3>Region</h3>
<ul>
<li>
<strong>URI</strong>: <% $base_uri %>region/<code>{id}</code>
</li>
<li>
<strong>Type</strong>: application/vnd.vegguide.org-region+json
</li>
</ul>
<p>
Returns a <a href="#Region">Region data structure</a>. These URIs show up in
any response that includes region URIs, including the top level response, a
region's list of child regions, and an entry's link to its containing
region.
</p>
<h3>Region Entries</h3>
<ul>
<li>
<strong>URI</strong>: <% $base_uri %>region/<code>{id}</code>/entries
</li>
<li>
<strong>Type</strong>: application/vnd.vegguide.org-entries+json
</li>
</ul>
<p>
Returns an array of <a href="#Region">Entry data structures</a> for the
region. This document only includes entries that are not marked as closed.
</p>
<h3>Entry</h3>
<ul>
<li>
<strong>URI</strong>: <% $base_uri %>entry/<code>{id}</code>
</li>
<li>
<strong>Type</strong>: application/vnd.vegguide.org-entry+json
</li>
</ul>
<p>
Returns a <a href="#Entry">Entry data structure</a>. These URIs show up in
any response that includes entry URIs, such as a region's entries list or
search results.
</p>
<h3>Entry Reviews</h3>
<ul>
<li>
<strong>URI</strong>: <% $base_uri %>entry/<code>{id}</code>/reviews
</li>
<li>
<strong>Type</strong>: application/vnd.vegguide.org-entry-reviews+json
</li>
</ul>
<p>
Returns an array of <a href="#Comment">Comment data structures</a>. These
URIs show up in any response that includes entry review URIs, such as a
entry's reviews list.
</p>
<h3>User</h3>
<ul>
<li>
<strong>URI</strong>: <% $base_uri %>user/<code>{id}</code>
</li>
<li>
<strong>Type</strong>: application/vnd.vegguide.org-user+json
</li>
</ul>
<p>
Returns a <a href="#User">User data structure</a>. These URIs show up in any
response that includes user URIs, such as an entry or image data structure.
</p>
<a name="Error-Responses"></a>
<h2>Error Responses</h2>
<p>
Error responses are accompanied by a JSON document body describing the error
except for errors in the 5xx range, which typically mean something went
wrong server side. The content type for errors is
always <em>application/vnd.vegguide.org-error+json</em>
</p>
<p>
Error bodies are a JSON object containing one key, <code>error</code>. The
value for this key is a user-readable message describing the error.
</p>
<h2>Release History</h2>
<h3>0.0.1 - September 1, 2012</h3>
<p>
First release upon an unsuspecting world.
</p>
<%init>
my $uri = $c->request()->uri();
my %port = $uri->port() != 80
&& $uri->port() != 443 ? ( port => $uri->port() ) : ();
my $base_uri = uri(
scheme => $uri->scheme(),
host => $uri->host(),
%port,
);
</%init>
</%def>
<%method page_title>
VegGuide.org REST API
</%method>
<%def .paging-param-rows>
<tr>
<td>limit</td>
<td>positive integer</td>
<td>50</td>
<td>
The maximum number of entries to return. This cannot be greater than
100.
</td>
</tr>
<tr>
<td>page</td>
<td>positive integer</td>
<td>1</td>
<td>
If there are more than <code>limit</code> entries in the search, this
parameter lets you fetch subsequent pages of results.
</td>
</tr>
</%def>
Jump to Line
Something went wrong with that request. Please try again.