contents of this page
API Reference¶
The root URL for all Parse.ly API requests is:
http://api.parse.ly/p
If you try to open http://api.parse.ly in a browser, you’re just going to hit a landing page. Each of our REST resources (as described from a high level in our Concepts document) is exposed as a URL below this root.
Exposed URLs¶
To keep things nice and organized, we have identified all the URLs exposed by our API in terms of a lightweight grammar.
Note
This grammar uses a subset of Perl, including string literal (“...”), string concatenation (.), and regex literal syntax (/.../). The named capturing groups use the PCRE syntax of (?P<param>...), where ... is a regular expression and param is the name of the capturing group. These named capture groups are distinct parameters passed along to our API.
The following are all the URLs exposed by the API.
# item query
"/user/items/" . /(?P<page_type>current|archived|deleted)/
"/user/items/matching/" . /(?P<query>[\w\d\+]+)/
"/user/items/dated/" . /(?P<from_date>[\d\w\-\:]+)/ . /(?P<to_date>[\d\w\-\:]*)/
"/user/items/status/" . /(?P<status_type>read|starred|archived|deleted)/
"/user/items/" . /(?P<signature_hash>[A-Za-z0-9]+)/ . "/status"
# channel query
"/channels/list/"
# data source management
"/user/source/create/"
"/user/source/list/"
"/user/source/update/" . /(?P<source_id>\d+)/
"/user/source/delete/" . /(?P<source_id>\d+)/
# interest management
"/user/interest/create/"
"/user/interest/list/"
"/user/interest/update/" . /(?P<interest_id>\d+)/
"/user/interest/delete/" . /(?P<interest_id>\d+)/
# profile management
"/user/profile/create/"
"/user/profile/list/"
"/user/profile/update/" . /(?P<profile_id>\d+)/
"/user/profile/delete/" . /(?P<profile_id>\d+)/
Testing and Poking Around¶
In order to test the Parse.ly API, the trickiest thing is to make sure that all of your HTTP requests are signed using the OAuth protocol. This is described in full detail in our OAuth background document; there is also a section there on setting up a proxy using the oauth_proxy tool. The examples of testing below assume that an oauth_proxy is already set up on your local development machine.
Testing with curl¶
A free and easy-to-use client-side library for HTTP requests and URL transfers is provided in most systems in the form of the curl executable (aka cURL).
The main argument that you need in order to make curl work with oauth_proxy is the -x or –proxy argument. In the standard oauth_proxy configuration described in OAuth, the proxy host is localhost:8001.
A basic request for all user profiles avilable ...
Testing with Firefox¶
Testing with RESTClient¶
UserProfile Operations¶
List¶
Output all UserProfile resources associated with your API key:
>>>> GET("/user/profile/list")
out> [
{
'interests': [{u'aliases': u'',
u'id': 7,
u'qualifiers': u'',
u'rank': 2,
u'term': u'!apple'}]
'user_profile': {u'api_user_id': 1,
u'email': u'nnw345y@not.com',
u'id': 2,
u'name': u'123nnn33',
u'user_id': 3}
}
]
Create¶
Create a new UserProfile resource and return its auto-generated identifier:
>>>> POST({
"user_profile":{"email": "nnw345y@not.com","name": "123nnn33"},
"interests": [{"term": "internet","alias": "ewewe","rank":6}
})
out> 1234
Update¶
Update a UserProfile, given a profile identifier. PUT data should be valid JSON. Example:
>>>> PUT("/user/profile/update/1234",
{
"user_profile":{"email": "nnw345y@not.com","name": "123nnn33"},
"interests": [{"term": "internet","alias": "ewewe","rank":6}
})
out> 1234
Delete¶
Delete a UserProfile, given a profile identifier. Example:
>>>> DELETE /user/profile/delete/<profile_id>
out> GONE