Two-Legged OAuth with Python¶

Not all OAuth client libraries have the same degree of support for 2-legged OAuth. Our Python client library includes a special module to implement 2-legged OAuth. Here’s an example of getting our ParselyClient connected to our server with the OAuth secret and key:

client  = parsely.ParselyClient(
    “DgB6Dcpzju2hX6xTwU”,
    “CqaDTFAkneDzZTre9TgCzd34JANKZQTm”,
    “api.parse.ly”)

Meaning of xoauth_requestor_id¶

One of the OAuth header keys that is required on almost all requests is xoauth_requestor_id. This is the identifier of the UserProfile instance for the data being requested. Not all OAuth client libraries support this key out of the box; let us know if you run into issues with it.

Setting up an oauth_proxy¶

In order to ergonomically test our API (e.g. using your browser and using command-line tools like curl), you can set up an OAuth Proxy. An OAuth proxy simply receives HTTP requests and forwards thems to another HTTP service, while signing every request with the proper OAuth header entries (as described in OAuth).

Luckily, Seth Fitzsimmons has written a handy little tool that does just that. You can find the tool at the oauth_proxy github repo or read his article about the tool.

Once you have this tool, simply set it up with the consumer key and shared secret we provided to you via e-mail. If you don’t have an API Key yet, contact us to get one.

Since we use two-legged OAuth, you only need to run the following:

$ cd oauth-proxy
$ twistd -n oauth_proxy
    –consumer-key <consumer key>
    –consumer-secret <consumer secret>

Then, you can make requests to the Parse.ly API using curl as follows:

$ curl -x localhost:8001 http://api.parse.ly/p/user/items/current

which should return data in JSON format.

If you run into issues getting a proper response from our server, feel free to contact us for help.

Principles¶

These are the principles that guided our API design:

• Aim to be RESTful: This has a controverial definition within the API community, but we followed some of the guidelines set forth in some of the REST resources listed here.
• Documented: We should document our API and interchange formats in a way that makes it easy for our users to find what they’re looking for and make the requests and interactions that they need to get their work done.
• Meaningful Error States: When there are problems finding requested data or if a service is down, we should have some well-established error states that can be handled gracefully by our clients.
• JSON as an interchange format: JSON is a lightweight and human-readable format. JSON’s only real drawback vs. something like XML is that there is no good way to define a JSON “schema” to document the formats formally. There is a jsonschema project to do this, but it’s still early days for that. So, we will just substitute a good schema for good documentation.
• Tested: The API should be tested, and, once it leaves “beta” state, it should be versioned and have a high degree of reliability and consistency.
• Language Bindings Included: RESTful API design really defines our wire format and mechanism for interacting with our server. But we should provide language bindings for various platforms to ease the ability to prototype applications atop the Parse.ly REST API.

Design Guidelines¶

Many of our design guidelines came from the excellent book by Leanard Richardson and Sam Ruby, RESTful Web Services, published by O’Reilly and the article A Brief Intro to REST.

We highly recommend you read that article and pick up a copy of the book if you ever need to design a service of your own!

interface Resource {
     Resource(URI u);
     Response get();
     Response post(Request r);
     Response put(Request r);
     Response delete();
}

Bibliography¶

This API was designed taking the following documents into consideration:

• A Brief Intro to REST
• Atlassian REST API Design Guidelines
• REST Anti-Patterns
• REST for the rest of us
• How I Explained REST to my Wife

What is JSON?¶

From http://json.org:

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language ...

Parse.ly JSON Usage¶

The Parse.ly API uses some standard JSON message formats for all of its request and response documents. We also follow some conventions that make our documents easier to produce and consume. These are described in more detail below:

{
  “meta”: { ... }
  “data”: { ... }
}

{
  “meta”: {
     “paging”: {
        “totalItems”: 59642,
        “pageNumber”: 1,
        “startIndex”: 0,
        “limit”: 125
     },
     “type”: “list<item>”
   },
   “data”:
        “articles”: [
            {
                “title”: “Parse.ly releases its Publisher Platform and API”,
                “score”: 10.0,
                “signature_hash”: “cbe668d4b7e2545cf4890ce1cf9bb47b”,
                “updated”: “2010-01-24 19:01:57”,
                “unique_id”: “LNqp” //, ...
            } //, ...
        ]
}

var response = getItemsResponse();
var articles = response.data.articles;
var meta = response.meta;

assert meta.type == “list<item>”;

for (var i = 0; i < articles.length; i++) {
    var article = articles[i];
    // do something with article
}

var response = getItemsResponse()
var meta = response.meta;
var articles = response.data.articles;
assert meta.type == “list<item>”;

var resultsTemplate = Ext.XTemplate(
      “<div id=’resultsNavigator’>”
       “Pg {pageNumber}: “,
       “Showing {limit} articles out of “,
       “{totalItems} articles total”
      “</div>”)

resultsTemplate.overwrite(meta.paging, Ext.get(“results”));

Exposed URLs¶

To keep things nice and organized, we have identified all the URLs exposed by our API in terms of a lightweight grammar.

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.

UserProfile Operations¶

>>>> 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}
        }
]

>>>> POST({
        “user_profile”:{“email”: “nnw345y@not.com”,”name”: “123nnn33”},
        “interests”: [{“term”: “internet”,”alias”: “ewewe”,”rank”:6}
    })
out> 1234

>>>> PUT(“/user/profile/update/1234”,
        {
            “user_profile”:{“email”: “nnw345y@not.com”,”name”: “123nnn33”},
            “interests”: [{“term”: “internet”,”alias”: “ewewe”,”rank”:6}
        })
out> 1234

>>>> DELETE /user/profile/delete/<profile_id>
out> GONE

What does the Tracker do?¶

Inserting the tracker on your site¶

Optimizing tracker placement¶

http://mrcoles.com/blog/how-tracking-scripts-affect-page-loads/

1. Licensed Uses and Restrictions¶

Parse.ly APIs are owned by Parse.ly and are licensed to you on a worldwide (except as limited below), non-exclusive, non-sublicenseable basis on the terms and conditions set forth herein. These Terms of Use define legal use of the Parse.ly APIs, all updates, revisions, substitutions, and any copies of the Parse.ly APIs made by or for you. All rights not expressly granted to you are reserved by Parse.ly.

1. Subject to the restrictions set forth in these Terms of Use, you may use the Parse.ly APIs and any updates provided by Parse.ly (in its sole discretion) solely to interface with Parse.ly’s proprietary content recommendation service (the “Parse.ly Service”). Your license to the Parse.ly APIs under these Terms of Use continues until it is terminated by either party. You may terminate the license by discontinuing use of all or any of the Parse.ly APIs. Parse.ly may terminate the license at any time for any reason. Parse.ly may make changes, upgrades, or discontinue all or any portion of any Parse.ly API at any time for any reason. These Terms of Use terminate automatically if (i) you violate any term of these Terms of Use, (ii) Parse.ly publicly posts a written notice of termination on Parse.ly’s Web site, (iii) Parse.ly sends a written notice of termination to you, or (iv) Parse.ly ceases providing access to the Parse.ly APIs to you. Upon the expiration or any termination of these Terms of Service, the license granted to you will terminate and you, at your expense, will promptly return all copies of the API and all Confidential Information in your possession to Parse.ly. The provisions of Sections 2, 3, 7, 8, 10, and 12 shall survive termination or expiration of this Agreement for any reason.
2. Your application may make automated calls or other data requests to or through the Parse.ly network (“Calls”). Parse.ly may at any time, and over any given period of time, limit the number of Calls you may send to the Parse.ly network, or prohibit any application created by you from sending Calls to the Parse.ly network, as Parse.ly deems appropriate in its sole discretion.
3. If your product or service uses or is based upon the Parse.ly APIs, then you will comply with any Parse.ly attribution policy as in effect from time to time.
4. You will use the APIs in compliance with all applicable laws, statutes, regulations, ordinances or other rules promulgated by governing authorities having jurisdiction over the parties,
5. You shall use instructions provided in the Parse.ly APIs to place application identification information (“API Key”) into any application or service you develop that incorporates or makes any use of the Parse.ly APIs. You can sign up for an API Key at http://parse.ly/p3. You must provide accurate identification, contact, and other information required as part of the registration process. You will NOT create any script or other automated tool that attempts to create multiple API Keys. You may not allow any third party to use your API Key for their own benefit.
6. You shall NOT:

1. use the Parse.ly APIs in any manner or for any purpose that violates any law or regulation, promotes illegal activities, violates third party rights or terms of service, violates any right of any person, including but not limited to intellectual property rights, rights of privacy, or rights of personality, or in any manner inconsistent with the Parse.ly TOS or these Terms of Use;
2. modify, adapt, alter, translate the API;
3. use the Parse.ly APIs to engage in spamming or other advertising or marketing activities that violate any applicable laws, regulations or generally-accepted advertising industry guidelines;
4. sell, lease, share, transfer, or sublicense the Parse.ly APIs, or access or access codes thereto, or derive income from the use or provision of the Parse.ly APIs, whether for direct commercial or monetary gain or otherwise, without Parse.ly’s prior, express, written permission;
5. use the Parse.ly APIs in a manner that adversely effects Parse.ly and/or the Parse.ly Service or exceeds: (a) reasonable request volume, as set by Parse.ly from time to time, (b) constitutes excessive or abusive usage, or (c) otherwise fails to comply or is inconsistent with any part of the Parse.ly API documentation, as determined by Parse.ly in its sole discretion;
6. otherwise exercise rights to the API except as expressly allowed by these Terms of Service;
7. reverse engineer or attempt to reconstruct, identify or discover any underlying ideas, underlying user interface techniques or algorithms related to the Parse.ly Service;
8. remove, obscure or alter any Parse.ly’s copyright notices, trademarks or other proprietary rights notices affixed to or contained within the API; or
9. use the Parse.ly APIs in a product or service that competes with products or services offered by Parse.ly, without Parse.ly’s prior, express, written permission.

Parse.ly reserves the right to immediately suspend access to the API if you breach any terms of these Terms.

2. Ownership and Relationship of Parties¶

The Parse.ly APIs may be protected by copyrights, trademarks, service marks, international treaties, and/or other proprietary rights and laws of the U.S. and other countries. Parse.ly’s rights apply to the Parse.ly APIs and all output and executables of the Parse.ly APIs, excluding any software components developed by you which do not themselves incorporate the Parse.ly APIs or any output or executables of the Parse.ly APIs. You agree to abide by all applicable proprietary rights laws and other laws, as well as any additional copyright notices or restrictions contained in these Terms of Use and in the TOS. Parse.ly owns all rights, title, and interest in and to the Parse.ly APIs. These Terms of Use grant you no right, title, or interest in any intellectual property owned or licensed by Parse.ly, including (but not limited to) the Parse.ly APIs and Parse.ly trademarks.

3. Confidentiality.¶

You acknowledge that the API is a commercially valuable asset which constitutes a trade secret of Parse.ly and that it contains Confidential Information proprietary to Parse.ly. For purposes of these Terms of Service, “Confidential Information” means the API, all information provided by Parse.ly about the API, and all information provided by Parse.ly that is clearly marked or identified as confidential or that a reasonable person would understand that such information is confidential. You shall not disclose Confidential Information to any third party or use Confidential Information for any purpose other than as expressly permitted by these terms of Service. You agree that you, including your employees, officers, and agents, if any, shall treat all Confidential Information with the same degree of care as it accords to your own confidential information but which, in no event, shall be less than reasonable care and shall not disclose, sell, transfer, publish, copy, display or otherwise make the API available, or any part thereof in any form, to any person or entity not a party to these Terms of Service. You shall take all reasonable precautions to ensure fulfillment of this confidentiality and nondisclosure obligations and agrees to immediately notify Parse.ly of any unauthorized use, copying and/or disclosure of the API, as well as, take such actions as are necessary to cease and prevent any further unauthorized use, copying and/or disclosure.

You acknowledge that any use or disclosure of the API by you in violation of or in any manner inconsistent with these Terms of Service would cause substantial and irreparable injury to Parse.ly, and that Parse.ly’s remedies at law will not be adequate. Accordingly, you agree that Parse.ly shall be entitled to injunctive relief with respect to any breach, or threatened breach of this Section, and that such right shall be in addition to, and not in limitation of, any other rights or remedies to which Parse.ly is or may be entitled at law or equity.

4. Support.¶

Parse.ly may elect to provide you with support or modifications for the Parse.ly APIs (collectively, “Support”), in its sole discretion, and may terminate such Support at any time without notice to you. Parse.ly may change, suspend, or discontinue any aspect of the Parse.ly APIs at any time, including the availability of any Parse.ly APIs. Parse.ly may also impose limits on certain features and services or restrict your access to parts or all of the Parse.ly APIs or the Parse.ly website without notice or liability.

5. Fees and Payments.¶

If more than a single individual user will be using or accessing the interface to the Parse.ly Services, you will pay Parse.ly a monthly license fee per user, as set forth on the order form accepted by Parse.ly. Parse.ly reserves the right to charge additional or different fees for future use of, support for, or access to the Parse.ly APIs or the Parse.ly Services in Parse.ly’s sole discretion provided that such charges will be disclosed in advance.

6. Copyright Complaints; Repeat Infringer Policy.¶

You agree to take whatever actions are necessary or are requested by Parse.ly to enable Parse.ly to comply with Parse.ly’s copyright policy and the take-down and other provisions of the Digital Millennium Copyright Act (“DMCA”) or other applicable laws and regulations with respect to your Parse.ly API. In addition, you acknowledge that in accordance with the DMCA and other applicable law, Parse.ly has adopted a policy of terminating, in appropriate circumstances and at its sole discretion, users and developers who are deemed to be repeat infringers, and that you agree that you will, if requested by Parse.ly, take reasonable steps to terminate access to your Parse.ly API for any user who Parse.ly identifies to you as a repeat infringer.

7. Disclaimer of Any Warranty.¶

SOME OF THE PARSE.LY APIS ARE EXPERIMENTAL AND HAVE NOT BEEN TESTED IN ANY MANNER. PARSE.LY DOES NOT REPRESENT OR WARRANT THAT ANY PARSE.LY APIS ARE FREE OF INACCURACIES, ERRORS, BUGS, OR INTERRUPTIONS, OR ARE RELIABLE, ACCURATE, COMPLETE, OR OTHERWISE VALID.

THE PARSE.LY APIS ARE PROVIDED “AS IS” WITH NO WARRANTY, EXPRESS OR IMPLIED, OF ANY KIND AND PARSE.LY EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES AND CONDITIONS, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AVAILABILITY, SECURITY, TITLE AND/OR NON-INFRINGEMENT. PARSE.LY DOES NOT WARRANT THAT THE API WILL OPERATE WITHOUT INTERRUPTION OR ERROR. NO WARRANTY IS MADE BY PARSE.LY ON THE BASIS OF TRADE USAGE, COURSE OF DEALING OR COURSE OF TRADE. PARSE.LY DOES NOT WARRANT THAT THE PARSE.LY PLATFORM OR PARSE.LY SERVICES WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE PARSE.LY PLATFORM WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT ALL ERRORS WILL BE CORRECTED.

YOUR USE OF PARSE.LY APIS IS AT YOUR OWN DISCRETION AND RISK, AND YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGE THAT RESULTS FROM THE USE OF ANY PARSE.LY APIS INCLUDING, BUT NOT LIMITED TO, ANY DAMAGE TO YOUR COMPUTER SYSTEM OR LOSS OF DATA.

8. Limitation of Liability.¶

PARSE.LY SHALL NOT, UNDER ANY CIRCUMSTANCES, BE LIABLE TO YOU FOR ANY INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL OR EXEMPLARY DAMAGES ARISING OUT OF OR IN CONNECTION WITH USE OF THE PARSE.LY APIS, WHETHER BASED ON BREACH OF CONTRACT, BREACH OF WARRANTY, TORT (INCLUDING NEGLIGENCE, PRODUCT LIABILITY OR OTHERWISE), OR ANY OTHER PECUNIARY LOSS, WHETHER OR NOT PARSE.LY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT SHALL PARSE.LY’S TOTAL AGGREGATE LIABILITY ARISING FROM OR RELATED TO THIS AGREEMENT, WHETHER IN CONTRACT OR IN TORT OR UNDER ANY OTHER LEGAL THEORY (INCLUDING STRICT LIABILITY AND NEGLIGENCE) EXCEED THE LESSER OF (A) THE TOTAL AMOUNT PAID TO PARSE.LY BY YOU DURING THE SIX (6) MONTH PERIOD IMMEDIATELY PRIOR TO THE EVENT GIVING RISE TO SUCH LIABILITY OR (B) ONE THOUSAND DOLLARS ($1,000).

9. Essential Basis; Exclusions and Limitations.¶

The parties acknowledge and agree that the disclaimers, exclusions and limitations of liability set forth in these Terms of Service form an essential basis of these terms of Service, and that, absent any of such disclaimers, exclusions or limitations of liability, the terms of these Terms of Service, including, without limitation, the economic terms, would be substantially different.

SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF CERTAIN WARRANTIES OR THE LIMITATION OR EXCLUSION OF LIABILITY FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES. ACCORDINGLY, SOME OF THE ABOVE LIMITATIONS OF SECTIONS 7 AND 8 MAY NOT APPLY TO YOU.

10. Release and Waiver.¶

To the maximum extent permitted by applicable law, you hereby release and waive all claims against Parse.ly, and its subsidiaries, affiliates, officers, agents, licensors, co-branders or other partners, and employees from any and all liability for claims, damages (actual and/or consequential), costs and expenses (including litigation costs and attorneys’ fees) of every kind and nature, arising from or in any way related to your use of Parse.ly APIs. If you are a California resident, you waive your rights under California Civil Code § 1542, which states, “A general release does not extend to claims which the creditor does not know or suspect to exist in his favor at the time of executing the release, which if known by him must have materially affected his settlement with the debtor.” You understand that any fact relating to any matter covered by this release may be found to be other than now believed to be true and you accept and assume the risk of such possible differences in fact. In addition, you expressly waive and relinquish any and all rights and benefits which you may have under any other state or federal statute or common law principle of similar effect, to the fullest extent permitted by law.

11. Release, Hold Harmless and Indemnity.¶

You irrevocably and unconditionally release and covenant not to use or pursue any claim against Parse.ly and its subsidiaries, affiliates, officers, agents, licensors, co-branders or other partners, and employees, for any and all damages, liabilities, causes of action, judgments, and claims: (i) pertaining to your Parse.ly API, or (ii) which otherwise may arise in connection with your use of, reliance on, or reference to the Parse.ly platform, documentation, or Parse.ly API.

To the maximum extent permitted by applicable law, you agree to hold harmless and indemnify Parse.ly and its subsidiaries, affiliates, officers, agents, licensors, co-branders or other partners, and employees from and against any third party claim arising from or in any way related to your use of Parse.ly APIs or any violation of these Terms of Use or TOS, including any liability or expense arising from all claims, losses, damages (actual and/or consequential), suits, judgments, litigation costs and attorneys’ fees, of every kind and nature. Parse.ly shall use good faith efforts to provide you with written notice of such claim, suit or action.

12. General Terms.¶

Notwithstanding any provision hereof, for all purposes of the Terms of Use, you and Parse.ly shall be and act independently and not as partner, joint venturer, agent, employee or employer of the other. You shall not have any authority to assume or create any obligation for or on behalf of Parse.ly, express or implied, and you shall not attempt to bind Parse.ly to any contract. If any provision of the Terms of Use is found by a court of competent jurisdiction to be invalid, the parties nevertheless agree that the court should endeavor to give effect to the parties’ intentions as reflected in the provision and the other provisions of such documents remain in full force and effect. The Terms of Use and the relationship between you and Parse.ly shall be governed by the laws of the State of Delaware without regard to its conflict of law provisions. You and Parse.ly agree to submit to the personal jurisdiction of the courts located within the State of Delaware. Parse.ly’s failure to exercise or enforce any right or provision of the Terms of Use shall not constitute a waiver of such right or provision. The section headings and subheadings contained in this agreement are included for convenience only, and shall not limit or otherwise affect the terms of the Terms of Use. Any construction or interpretation to be made of the Terms of Use shall not be construed against the drafter. The Terms of Use constitute the entire agreement between Parse.ly and you with respect to the subject matter hereof. You may not assign any of your rights or obligations under these Terms of Service without the prior written consent of Parse.ly. Any attempted assignment or transfer in violation of the foregoing will be void. No failure of either party to enforce any of its rights under these Terms of Service will act as a waiver of those rights.

Last updated: [January] 2010 / 428478 v2/RE