Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Updated readme to the new methods

  • Loading branch information...
commit c0928b3d3d2668892295073ed562a9ecc313450b 1 parent d9e6897
andzdroid authored June 17, 2011

Showing 1 changed file with 108 additions and 94 deletions. Show diff stats Hide diff stats

  1. 202  README.md
202  README.md
Source Rendered
@@ -22,142 +22,156 @@ Then call the `auth` method to fetch the user's API token.
22 22
       //API token fetched, you can now use all the API methods!
23 23
     });
24 24
 
25  
-## Callbacks
26  
-All API methods have the same callback:
  25
+## Methods
  26
+`get(api name, [args,] options, callback)`
27 27
 
28  
-`err` - contains the error message if there was an error, or null otherwise.
  28
+This makes GET request to the API endpoint specified by `api name`.
29 29
 
30  
-`results` - contains the results of the API call, see the [Posterous API](http://posterous.com/api) for more info.
  30
+Some API endpoints require arguments such as a site ID, or post ID, and these should be passed as the parameters after the api name.
  31
+
  32
+The `options` parameter is used for POST and PUT requests, where you will want to include body data. For more info on which options are available to each type of request, see the [Posterous API docs](http://posterous.com/api).
  33
+
  34
+The callback function will be used to return error messages or request results.
  35
+
  36
+The same applies to the following functions for different request methods:
  37
+
  38
+`post(api name, [args,] options, callback)`
31 39
 
  40
+`put(api name, [args,] options, callback)`
  41
+
  42
+`del(api name, [args,] options, callback)`
32 43
 
33  
-# API Methods
34  
-## Users
35 44
 ### auth(callback)
36 45
 `auth` will fetch the API token and save it to the Posterous object for future method calls. After you call auth, you don't need to do anything yourself with the API token.
37 46
 
38 47
 The callback for `auth` is slightly different: `result` will contain the API token directly as a string.
39 48
 
40  
-### getUser(callback)
41  
-`getUser` retrieves the current user's information, corresponding to the API endpoint of `users/me` in the docs.
42  
-
43  
-## User Subscriptions
44  
-### getSubscriptions([page number,] callback)
45  
-`getSubscriptions` retrieves a list of the user's current subscriptions, corresponding to the API endpoint of `users/me/subscriptions`.
  49
+__auth should be called before any other API requests, except for public APIs.__
46 50
 
47  
-There is an optional first parameter for specifying the page number of the results.
48 51
 
49  
-### getSubscriptionPosts([page number,] callback)
50  
-`getSubscriptionPosts` retrieves a list of posts from the user's subscribed sites, corresponding to the API endpoint of `users/me/subscriptions/posts`.
51  
-
52  
-There is an optional first parameter for specifying the page number of the results.
  52
+## Callbacks
  53
+All API methods have the same callback:
53 54
 
54  
-## Sites
55  
-### getSites(callback)
56  
-`getSites` retrieves a list of the user's Posterous sites, corresponding to the API endpoint of `sites`.
  55
+`err` - contains the error message if there was an error, or null otherwise.
57 56
 
58  
-### createSite(options, callback)
59  
-`createSite` creates a new Posterous site for the user, corresponding to the API endpoint of `sites`.
  57
+`results` - contains the results of the API call, see the [Posterous API](http://posterous.com/api) for more info.
60 58
 
61  
-The options parameter should be an object corresponding to the options in the docs for this API method:
62 59
 
63  
-    {
64  
-      'site[hostname]': hostname,
65  
-      'site[virtual_host]': virtualhost,
66  
-      'site[name]': name,
67  
-      'site[is_private]': 'false',
68  
-      'site[is_group]': 'false',
69  
-      'site[time_zone]': 'UTC',
70  
-      'site[subhead]': subhead
71  
-    }
  60
+# APIs
  61
+## User (GET)
  62
+Get the current user's information.
72 63
 
73  
-**site[hostname]** and **site[name]** are required options.
  64
+## Users (POST)
  65
+Create a new user (only for platform users of Posterous).
74 66
 
75  
-See the API docs for descriptions of the options.
  67
+## Subscriptions (GET)
  68
+The user's current subscriptions.
76 69
 
77  
-The result will be in the same format as the data returned by `getSites`.
  70
+## SubscriptionPosts (GET)
  71
+The posts from the user's subscribed sites.
78 72
 
79  
-### getSite(id, callback)
80  
-`getSite` fetches the details of a site, specified with the *site id*. This method corresponds to the APi endpoint of `sites/:id`.
  73
+## Sites (GET, POST)
  74
+List the user's Posterous sites, or create new sites.
81 75
 
82  
-### updateSite(id, options, callback)
83  
-`updateSite` updates a site's details with the same options as in `createSite`. This method corresponds to the API endpoint `sites/:id`.
  76
+## Site (GET, PUT, DELETE)
  77
+__Args:__ site ID
  78
+Get a single Posterous site, update it, or delete it.
84 79
 
85  
-### deleteSite(id, callback)
86  
-`deleteSite` deletes the Posterous site specified by the *site id*. This method corresponds to the API endpoint `sites/:id`.
  80
+## Photos (GET)
  81
+__Args:__ site ID
  82
+Get 20 random photos from the user's sites.
87 83
 
88  
-### getPhotos(id, options, callback)
89  
-`getPhotos` gets 20 random photos from a Posterous specified by the *site id*. This method corresponds to the API endpoint `sites/:id/photos`.
  84
+## Subscribe (GET)
  85
+__Args:__ site ID
  86
+Subscribe the current user to a site.
90 87
 
91  
-The possible keys in the `options` dictionary are `page` which determines which page of photos to return, and `since_id`, which will restrict photos to those attached to posts after the post with the provided ID. (See API docs for more info)
  88
+## Unsubscribe (GET)
  89
+__Args:__ site ID
  90
+Unsubscribe the current user from a site.
92 91
 
93  
-## Site Profiles
94  
-### getSiteProfile(id, callback)
95  
-`getSiteProfile` corresponds to the API endpoint `sites/:id/profile`.
  92
+## HeaderImage (POST, DELETE)
  93
+__Args:__ site ID
  94
+Upload a new header image, or delete it.
96 95
 
97  
-### createSiteProfile(id, options, callback)
98  
-`createSiteProfile` creates a new profile for a site. This method corresponds to the API endpoint `sites/:id/profile`.
  96
+## SiteProfile (GET, POST, PUT, DELETE)
  97
+__Args:__ site ID
  98
+Get, create, update, delete a site's profile.
99 99
 
100  
-The options parameter must be a dictionary with the following options:
  100
+## SiteProfileImage (PUT, DELETE)
  101
+__Args:__ site ID
  102
+Upload or delete a site's profile image.
101 103
 
102  
-    {
103  
-      'site_profile[group_profile_name]': 'The site profile name',
104  
-      'site_profile[body]': 'Profile information and bio'
105  
-    }
  104
+## Tags (GET)
  105
+__Args:__ site ID
  106
+Get the list of tags for a site.
106 107
 
107  
-See the Posterous API docs for more info.
  108
+## Contributors (GET, POST)
  109
+__Args:__ site ID
  110
+Get the list of contributors, or add a new contributor.
108 111
 
109  
-### updateSiteProfile(id, options, callback)
110  
-`updateSiteProfile` updates the profile for a site, and corresponds to the API endpoint `sites/:id/profile`.
  112
+## Contributor (DELETE)
  113
+__Args:__ site ID, contributor ID
  114
+Delete a contributor from a site.
111 115
 
112  
-The options parameter must be the same as in `createSiteProfile`.
  116
+## Subscribers (GET, POST)
  117
+__Args:__ site ID
  118
+Get a list of subscribers to a site, or add a new subscriber (Platform users only).
113 119
 
114  
-### deleteSiteProfile(id, callback)
115  
-`deleteSiteProfile` corresponds to the API endpoint `sites/:id/profile`.
  120
+## Subscriber (DELETE)
  121
+__Args:__ site ID, subscriber ID
  122
+Remove a subscriber from a site.
116 123
 
117  
-### updateSiteProfileImage(id, file, callback)
118  
-`updateSiteProfileImage` uploads a new profile image. This method corresponds to the API endpoint `sites/:id/profile/image`.
  124
+## ExternalSites (GET)
  125
+__Args:__ site ID
  126
+Get a list of external autopost sites.
119 127
 
120  
-### deleteSiteProfileImage(id, callback)
121  
-`deleteSiteProfileImage` deletes the existing profile image. This method corresponds to the API endpoint `sites/:id/profile/image`.
  128
+## ExternalSite (GET, DELETE)
  129
+__Args:__ site ID, external site ID
  130
+Get or delete a single external autopost site.
122 131
 
123  
-## Subscribe to site
124  
-### subscribe(id, callback)
125  
-`subscribe` subscribes the current user to the site specified by the *site id*. This method corresponds to the API endpoint `sites/:id/subscribe`.
  132
+## Theme (GET, POST)
  133
+__Args:__ site ID
  134
+Get the theme for a site, or create a new theme.
126 135
 
127  
-### unsubscribe(id, callback)
128  
-`unsubscribe` removes the user's subscription to the site specified by the *site id*. This method corresponds to the API endpoint `sites/:id/unsubscribe`.
  136
+## AllPosts (GET)
  137
+Get a list of public posts.
129 138
 
130  
-## Site header
131  
-### setHeader(id, file, callback)
132  
-`setHeader` sets a new header image for the site. This method corresponds to the API endpoint `sites/:id/header_image`.
  139
+## Posts (GET, POST)
  140
+__Args:__ site ID
  141
+Get a list of posts belonging to a site, or create a new post.
133 142
 
134  
-### deleteHeader(id, callback)
135  
-`deleteHeader` removes the header image for the site specified by the *site id*. This method corresponds to the API endpoint `sites/:id/header_image`.
  143
+## PublicPosts (GET)
  144
+__Args:__ site ID
  145
+Get a list of a site's public posts.
136 146
 
137  
-## Tags
138  
-### getTags(id, callback)
139  
-`getTags` retrieves the tags associated with a site. This method corresponds to the API endpoint `sites/:id/tags`.
  147
+## Post (GET, PUT, DELETE)
  148
+__Args:__ site ID, post ID
  149
+Get a single post, update it or delete it.
140 150
 
141  
-## Contributors
142  
-### getContributors(id, callback)
143  
-`getContributors` retrieves the contributors of a Posterous. This method corresponds to the API endpoint `sites/:id/contributors`.
  151
+## PostPhotos (GET)
  152
+__Args:__ site ID, post ID
  153
+Get photos from a post.
144 154
 
145  
-### removeContributor(id, user, callback)
146  
-`removeContributor` removes a user (specified by ID) from the list of contributors of a site. This method corresponds to the API endpoint `sites/:id/contributors/:user`.
  155
+## PostVideos (GET)
  156
+__Args:__ site ID, post ID
  157
+Get videos from a post.
147 158
 
148  
-## Subscribers
149  
-### getSubscribers(id, callback)
150  
-`getSubscribers` retrieves the subscribers of a Posterous. This method corresponds to the API endpoint `sites/:id/subscribers`.
  159
+## PostAudioFiles (GET)
  160
+__Args:__ site ID, post ID
  161
+Get audo files from a post.
151 162
 
152  
-### removeSubscriber(id, user, callback)
153  
-`removeSubscriber` removes a user (specified by ID) from the list of subscribers of a site. This method corresponds to the API endpoint `sites/:id/subscribers/:user`.
  163
+## Comments (GET, POST)
  164
+__Args:__ site ID, post ID
  165
+Get a list of comments from a post, or create a new comment.
154 166
 
155  
-## External Autopost sites
156  
-### getAutopostSites(id, callback)
157  
-`getAutopostSites` retrieves a list of all external autopost sites for a Posterous. This method corresponds to the API endpoint `sites/:id/external_sites`.
  167
+## Comment (GET, PUT, DELETE)
  168
+__Args:__ site ID, post ID, comment ID
  169
+Get a single comment from a post, update it, or delete it.
158 170
 
159  
-### getAutopostSite(id, autopost\_id, callback)
160  
-`getAutopostSite` retrieves a single external autopost site by its ID. This method corresponds to the API endpoint `sites/:id/external_sites/:autopost_id`.
  171
+## Likes (GET, POST)
  172
+__Args:__ site ID, post ID
  173
+Get a list of likes for a post, or add a new like.
161 174
 
162  
-### deleteAutopostSite(id, autopost\_id, callback)
163  
-`deleteAutopostSite` removes a single external autopost site by ID. This method corresponds ot the API endpoint `sites/:id/external_sites/:autopost_id`.
  175
+## Like (GET, DELETE)
  176
+__Args:__ site ID, post ID, like ID
  177
+Get a single like for a post, or delete it.

0 notes on commit c0928b3

Please sign in to comment.
Something went wrong with that request. Please try again.