Urgeous API

Urgeous' API lets users retrieve posts to serve them from their own pages / domain / etc. The API responds with either XML, JSON or HTML; every response can include the content of the posts together with metadata.

The concept

Here's how it works

• make a request to the API
• receive a list of posts (metadata and/or actual posts content)
• process this list to display it

Try it now!

API key

In order to use the API you must first get an API key by sending an email to request_api@urgeous.com.

(You can also test the API without your own personal key, by using the special test key 'keyfortests' (without quotes); this special key responds with always the same results -- so you really should get your own key! ;-)

Once you get your key you can start building requests.

Getting started

The API is available at http://api.urgeous.com/v01/ and the only action currently available is "list" (to query posts), so all your requests should start with:

http://api.urgeous.com/v01/list

You can query

• all posts by a given user (given a user id)
• a specific post (given a post id)

The posts in the response are in reverse chronological order.

To query all posts by a given user you should provide the following parameters

• uid: a user id (always start with a u)
• mode: "user"

To query a specific post you should provide this:

• pid: a post id (always starts with a p)
• mode: "post"

So, for example, in order to retrieve all posts by user "u38t3aaa405" you can do this:

http://api.urgeous.com/v01/list?key=keyfortests&uid=u38t3aaa405&mode=user&show=yes

This is almost the same example as above, except that in this case, we added the parameter "show=yes" so that the request includes the content of the posts.

Response formats

By default, the API responds in XML, but you can request JSON instead with the "format" parameter:

http://api.urgeous.com/v01/list?key=keyfortests&uid=u38t3aaa405&mode=user&format=json

This would give you something like this:

The "format" parameter also accepts "html" as a value. This returns an HTML fragment (a div) that you can serve directly without further processing on the server side:

(Note that all metadata are included as data attributes).

Complete API reference

Responses are encoded using UTF-8. Posts are returned in reverse chronological order.

The header of the response describes the parameters it has received or their current value when this was changed using defaults.

In case of errors, the cause of the error is included (where possible) and an error code is returned (loosely inspired by HTTP error codes).

The following parameters are available:

• key

  • api key
  • required
  • you can use 'keyfortests' to test

• mode

  • request mode (all posts from a user|a specific post)
  • required
  • possible values: user|post

• uid

  • user id
  • required if mode==user

• pid

  • post id
  • required if mode==post

• format

  • expected response format
  • optional
  • possible values: xml|json|html
  • default: xml

• show

  • include content of posts in the response
  • optional
  • possible values: yes|no
  • default: no

• source

  • format of the post (HTML or 'raw' (Markdown))
  • optional
  • possible values: html|md
  • default: html

• offset

  • offset in the list of posts
  • optional
  • possible values: > 0
  • default: n/a

• limit

  • number of posts returned
  • optional
  • possible values: 1 < limit < 100
  • default: 10

Happy coding! And don't forget we're here to help if needed: support@urgeous.com

2013-03-01 by u52t3aaa404 (RSS) • reply • flagpost • home