ADGETS| Attachments: | http-client.pl |
POST API
In subversion, there is a new file lib/Gadgets/Standard/Post/HTTP.pm. It implements a mod_perl handler implementing a Gadget Post Service that can be configured using an Apache Location directive, like so:
<Location "/post/service/">
SetHandler perl-script
PerlHandler Gadgets::Standard::Post::HTTP
</Location>
The rest of this document assumes that the service is located at /post/service/.
The service accepts GET requests (to read a post), POST requests (to make a new post or reply to an existing post), and PUT requests (to edit an existing post).
Required Headers
A valid username and password is required for all requests to the service. They are sent in the X-Gadgets-Post-Username and X-Gadgets-Post-Password headers, respectively. If there is an error authenticating, the service returns a AUTH_REQUIRED status code and sets a message in the X-Gadgets-Post-Authenticate-Error header in the response.
Reading Posts
GET requests need a doc key in the url, like so: http://wiki.oblong.net/post/service/Post|main|07NGOqmsS-Yx2OMN. If the post is not found, the status code NOT_FOUND is returned. If the authenticated user doesn't have permission to view the post, a FORBIDDEN response is returned. Assuming that the post exists and the authenticated user has permission to view the post, the following headers will be included in the response:
X-Gadgets-Post-Doc-Key [the doc key]
X-Gadgets-Post-Title [the title]
X-Gadgets-Post-Tags [a comma separated list of the tags]
X-Gadgets-Post-Owner [the doc key of the owner of the post]
X-Gadgets-Post-Perms-Post [a comma separated list of User/Group doc keys]
X-Gadgets-Post-Perms-Write [a comma separated list of User/Group doc keys]
X-Gadgets-Post-Perms-Read [a comma separated list of User/Group doc keys]
The body of the response will contain the body of post.
Creating New Posts
note Currently, only the "application/x-www-form-urlencoded" content type is supported for POST and PUT. It is the client authors responsibility to set the content-type header, as well as URI encode the body of the POST or PUT.
POST requests must not include a doc key, the post directly to the service, like so: http://wiki.oblong.net/post/service/. The following headers may be included in the request to the service:
X-Gadgets-Post-Title [the title]
X-Gadgets-Post-Tags [a comma separated list of the tags]
X-Gadgets-Post-Perms-Post [a comma separated list of User/Group doc keys]
X-Gadgets-Post-Perms-Write [a comma separated list of User/Group doc keys]
X-Gadgets-Post-Perms-Read [a comma separated list of User/Group doc keys]
X-Gadgets-Post-Is-Draft [a true value makes the post a draft]
X-Gadgets-Post-Is-Reply-To [the doc key of the post this is a reply to]
The body of the request becomes the body of the post that is created by the request. The response of the request is same as if a GET was requested to the post created.
Editing Existing Posts
PUT requests need a doc key in the url, like so: http://wiki.oblong.net/post/service/Post|main|07NGOqmsS-Yx2OMN. If the post is not found, the status code NOT_FOUND is returned. If the authenticated user doesn't have permission to view the post, a FORBIDDEN response is returned.
The following headers may be included in the request to the service:
X-Gadgets-Post-Title [the title]
X-Gadgets-Post-Tags [a comma separated list of the tags]
X-Gadgets-Post-Perms-Post [a comma separated list of User/Group doc keys]
X-Gadgets-Post-Perms-Write [a comma separated list of User/Group doc keys]
X-Gadgets-Post-Perms-Read [a comma separated list of User/Group doc keys]
The body of the request becomes the body of the post that is being edited by the request. The response of the request is same as if a GET was requested to the post edited.
Headers Reference
X-Gadgets-Post-Username
X-Gadgets-Post-Password
X-Gadgets-Post-Authenticate-Error
X-Gadgets-Post-Is-Reply-To
X-Gadgets-Post-Title
X-Gadgets-Post-Tags
X-Gadgets-Post-Perms-Post
X-Gadgets-Post-Perms-Write
X-Gadgets-Post-Perms-Read
X-Gadgets-Post-Perms-Error
X-Gadgets-Post-Is-Draft
X-Gadgets-Post-No-Store
X-Gadgets-Post-Doc-Key
X-Gadgets-Post-Owner
Attached is a Perl script that exercises the POST API.