Difference between revisions of "API Usage Guide"

From SailBlogs Support Wiki
Jump to: navigation, search
(→‎dt=allxp)
 
(6 intermediate revisions by the same user not shown)
Line 12: Line 12:
 
===dt===
 
===dt===
 
Datatype indicator. This tells the API what kind of information you're requesting. Possible values are:
 
Datatype indicator. This tells the API what kind of information you're requesting. Possible values are:
 +
* test
 
* blog
 
* blog
 
** items
 
** items
Line 19: Line 20:
 
* curxp
 
* curxp
 
* curpc
 
* curpc
−
* test
+
** pcID
 +
 
 +
====dt=test====
 +
Returns some information about the authorized user. This is a good way to test authorization.
 +
 
 +
<pre>http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=test</pre>
 +
 
 +
Output:
 +
<pre>
 +
<xjournal>
 +
  <api_res>0</api_res>
 +
  <api_res_msg>Ok</api_res_msg>
 +
  <user>
 +
      <blogID>8890</blogID>
 +
      <blogTitle>Sailblogs Demo</blogTitle>
 +
      <blogDir>sailblogsdemo</blogDir>
 +
      <blogURL>http://www.sailblogs.com/member/sailblogsdemo</blogURL>
 +
      <altTitle>Demo</altTitle>
 +
      <avatarMicro>mt_sb2w958s.jpg</avatarMicro>
 +
      <xpTeamID>776</xpTeamID>
 +
  </user>
 +
</xjournal>
 +
</pre>
  
 
====dt=blog====
 
====dt=blog====
 +
Returns blog post information for the authorized user.
 +
 
<pre>http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=blog</pre>
 
<pre>http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=blog</pre>
  
Line 31: Line 56:
 
       <msgID>114806</msgID>
 
       <msgID>114806</msgID>
 
       <postDate>2009-09-29 11:09:37</postDate>
 
       <postDate>2009-09-29 11:09:37</postDate>
−
       <title>This is test entry 3 with a lat/long included</title>
+
       <title><![CDATA[This is test entry 3 with a lat/long included]]></title>
−
       <location>Minneapolis</location>
+
       <location><![CDATA[Minneapolis]]></location>
−
       <author></author>
+
       <author><![CDATA[]]></author>
 
       <imageFile/>
 
       <imageFile/>
 
       <thumbnail/>
 
       <thumbnail/>
−
       <teaser>
+
       <teaser><![CDATA[
 
       This is a blog post that includes a lat/long reference and a youtube video:
 
       This is a blog post that includes a lat/long reference and a youtube video:
  
Line 42: Line 67:
  
 
       Line below video...
 
       Line below video...
−
       </teaser>
+
       ]]></teaser>
−
       <body>
+
       <body>![CDATA[
 
       This is a blog post that includes a lat/long reference and a youtube video:
 
       This is a blog post that includes a lat/long reference and a youtube video:
 
        
 
        
Line 49: Line 74:
  
 
       Line below video...
 
       Line below video...
−
       </body>
+
       ]]></body>
 
       <comments>0</comments>
 
       <comments>0</comments>
 
       <nextmsg/>
 
       <nextmsg/>
Line 85: Line 110:
 
       <author></author>
 
       <author></author>
 
       <imageFile/>
 
       <imageFile/>
−
       <display/>
+
       <display>1</display>
 
   </entry>
 
   </entry>
 
   <entry>
 
   <entry>
Line 94: Line 119:
 
       <author>Tim</author>
 
       <author>Tim</author>
 
       <imageFile/>
 
       <imageFile/>
−
       <display/>
+
       <display>1</display>
 
   </entry>
 
   </entry>
 
   <entry>
 
   <entry>
Line 103: Line 128:
 
       <author></author>
 
       <author></author>
 
       <imageFile>p1010001_scale.jpg</imageFile>
 
       <imageFile>p1010001_scale.jpg</imageFile>
−
       <display>p1010001_scale.jpg</display>
+
       <display>1</display>
 
   </entry>
 
   </entry>
 
</xjournal>
 
</xjournal>
Line 113: Line 138:
 
<pre>http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=comments&msgID=103152</pre>
 
<pre>http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=comments&msgID=103152</pre>
  
−
Returns:
+
Output:
  
 
<pre>
 
<pre>
Line 136: Line 161:
  
 
====dt=curxp====
 
====dt=curxp====
−
Will return current XPlot position information available for the authorized user.
+
====dt=allxp====
 +
Will return current XPlot position information available for the authorized user. '''curxp''' returns the current position only, '''allxp''' returns ALL of the position points for a user as "position" elements in the XML file.
  
 
<pre>http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=curxp</pre>
 
<pre>http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=curxp</pre>
  
−
Returns:
+
Output:
  
 
<pre>
 
<pre>
Line 158: Line 184:
 
       <pData2/>
 
       <pData2/>
 
       <pData3/>
 
       <pData3/>
 +
      <poleDistMi>3455.5673645175</poleDistMi>
 +
      <poleDistNMi>2999.3676036777</poleDistNMi>
 +
      <poleDistKm>5554.829115892</poleDistKm>
 
       <blogID/>
 
       <blogID/>
 
       <teamID>776</teamID>
 
       <teamID>776</teamID>
Line 165: Line 194:
 
</xjournal>
 
</xjournal>
 
</pre>
 
</pre>
 +
 +
'''poleDist__''' nodes will appear only if the user has selected a polar map for their display.
  
 
====dt=curpc====
 
====dt=curpc====
Line 171: Line 202:
 
<pre>http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=curpc&pcID=1</pre>
 
<pre>http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=curpc&pcID=1</pre>
  
−
Returns:
+
Output:
  
 
<pre>
 
<pre>
Line 189: Line 220:
  
 
There will be a "pcentry" block for each entry added to a particular podcast.
 
There will be a "pcentry" block for each entry added to a particular podcast.
 +
 +
==Errors==
 +
 +
Errors are also returned via XML. An error includes the error number, and a message (this allows developers to create custom error messages). An '''api_res''' value greater than zero indicates an error.
 +
 +
<pre>
 +
<xjournal>
 +
  <api_res>11</api_res>
 +
  <api_res_msg>No comments for this entry.</api_res_msg>
 +
</xjournal>

Latest revision as of 21:25, 23 November 2012

The following section describes the HTTP requests that can be made to the SailBlogs server, and the XML response that is returned.

Base URL

All calls to the SailBlogs API will be made to the following URL: 

http://www.sailblogs.com/api/sbapi.php

URL Parameters

auth

Authorization key. This is REQUIRED for all API calls. 

http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,

dt

Datatype indicator. This tells the API what kind of information you're requesting. Possible values are:

  • test
  • blog
    • items
  • contents
  • comments
    • msgID
  • curxp
  • curpc
    • pcID

dt=test

Returns some information about the authorized user. This is a good way to test authorization. 

http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=test

Output: 

<xjournal>
   <api_res>0</api_res>
   <api_res_msg>Ok</api_res_msg>
   <user>
      <blogID>8890</blogID>
      <blogTitle>Sailblogs Demo</blogTitle>
      <blogDir>sailblogsdemo</blogDir>
      <blogURL>http://www.sailblogs.com/member/sailblogsdemo</blogURL>
      <altTitle>Demo</altTitle>
      <avatarMicro>mt_sb2w958s.jpg</avatarMicro>
      <xpTeamID>776</xpTeamID>
   </user>
</xjournal>

dt=blog

Returns blog post information for the authorized user. 

http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=blog

Output: 

<xjournal>
   <api_res>0</api_res>
   <api_res_msg>Ok</api_res_msg>
   <entry>
      <msgID>114806</msgID>
      <postDate>2009-09-29 11:09:37</postDate>
      <title><![CDATA[This is test entry 3 with a lat/long included]]></title>
      <location><![CDATA[Minneapolis]]></location>
      <author><![CDATA[]]></author>
      <imageFile/>
      <thumbnail/>
      <teaser><![CDATA[
      This is a blog post that includes a lat/long reference and a youtube video:

      [%youtube*http://www.youtube.com/watch?v=-lriRLdiAQE%v]

      Line below video...
      ]]></teaser>
      <body>![CDATA[
      This is a blog post that includes a lat/long reference and a youtube video:
      
      [%youtube*http://www.youtube.com/watch?v=-lriRLdiAQE%v]

      Line below video...
      ]]></body>
      <comments>0</comments>
      <nextmsg/>
      <prevmsg/>
      <latitude>44 57.22'N</latitude>
      <longitude>193 22.36'W</longitude>
      <declat>44.9537</declat>
      <declong>-193.3727</declong>
   </entry>
</xjournal>

If the items parameter is included, the system will return the number of blog posts requested: 

http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=blog&items=3

The above will return the three most recent entries.

dt=contents

Returns the table of contents for a particular blog: 

http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=contents

Output: 

<xjournal>
   <api_res>0</api_res>
   <api_res_msg>Ok</api_res_msg>
   <entry>
      <msgID>114806</msgID>
      <postDate>2009-09-29 11:09:37</postDate>
      <title>This is test entry 3 with a lat/long included</title>
      <location>Minneapolis</location>
      <author></author>
      <imageFile/>
      <display>1</display>
   </entry>
   <entry>
      <msgID>114804</msgID>
      <postDate>2009-09-28 11:06:19</postDate>
      <title>This is entry number 2</title>
      <location>Minneapolis</location>
      <author>Tim</author>
      <imageFile/>
      <display>1</display>
   </entry>
   <entry>
      <msgID>103152</msgID>
      <postDate>2009-09-27 10:50:36</postDate>
      <title>This is my first entry</title>
      <location></location>
      <author></author>
      <imageFile>p1010001_scale.jpg</imageFile>
      <display>1</display>
   </entry>
</xjournal>

dt=comments

Also requires the msgID parameter. Will return the comments available for a particular blog post. 

http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=comments&msgID=103152

Output: 

<xjournal>
   <api_res>0</api_res>
   <api_res_msg>Ok</api_res_msg>
   <comment>
      <msgID>103152</msgID>
      <blogID>8890</blogID>
      <posterName>Tim Harincar</posterName>
      <posterEmail>demo@sailblogs.com</posterEmail>
      <posterIP>207.250.230.131</posterIP>
      <comments>this is a test comment</comments>
      <postDate>2010-01-19 10:48:07</postDate>
      <display>1</display>
      <xj_ownerID>8887</xj_ownerID>
   </comment>
</xjournal>

There will be a "comment" block for each comment added to a particular post. If the msgID parameter is not included, the system will return an error message.

dt=curxp

dt=allxp

Will return current XPlot position information available for the authorized user. curxp returns the current position only, allxp returns ALL of the position points for a user as "position" elements in the XML file. 

http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=curxp

Output: 

<xjournal>
   <api_res>0</api_res>
   <api_res_msg>Ok</api_res_msg>
   <position>
      <posID>36846</posID>
      <latitude>44 12.57'N</latitude>
      <longitude>-117.2075</longitude>
      <declat>44.2095</declat>
      <declong>-117.0035</declong>
      <plotTime>2010-01-19 16:24:36</plotTime>
      <course/>
      <speed/>
      <pData1/>
      <pData2/>
      <pData3/>
      <poleDistMi>3455.5673645175</poleDistMi>
      <poleDistNMi>2999.3676036777</poleDistNMi>
      <poleDistKm>5554.829115892</poleDistKm>
      <blogID/>
      <teamID>776</teamID>
      <mapID>43</mapID>
      <xj_msgID>0</xj_msgID>
   </position>
</xjournal>

poleDist__ nodes will appear only if the user has selected a polar map for their display.

dt=curpc

Also requires the pcID parameter. Will return the latest podcast information for the authorized user. 

http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=curpc&pcID=1

Output: 

<xjournal>
   <api_res>0</api_res>
   <api_res_msg>Ok</api_res_msg>
   <pcentry>
      <mp3ID>371</mp3ID>
      <blogID>158</blogID>
      <podcastID>1</podcastID>
      <mp3File>b158_1262854986.mp3</mp3File>
      <mp3Date>2010-01-07 03:03:15</mp3Date>
      <display>1</display>
   </pcentry>
</xjournal>

There will be a "pcentry" block for each entry added to a particular podcast.

Errors

Errors are also returned via XML. An error includes the error number, and a message (this allows developers to create custom error messages). An api_res value greater than zero indicates an error. 

<xjournal>
   <api_res>11</api_res>
   <api_res_msg>No comments for this entry.</api_res_msg>
</xjournal>
Retrieved from "https://www.sailblogs.com/wiki/index.php?title=API_Usage_Guide&oldid=614"