How to handle API responses

Response Format

Our API can serve XML or JSON. Given a API endpoint, just add the format you want as a query string.

• XML format: Add ?format=xml at the end of the API endpoint url
• JSON format: Add ?format=json at the end of the API endpoint url

Pagination

Expect results to be paginated. If you want to fetch all the data one API endpoint can provide, you will have to go through all the pages yourself.

In JSON, responses from our API look like this:

{
    'count': 142,
    'next': 'http://homelocpay.net/api_endpoint/?page=2&format=json'
    'previous': null,
    'results': [
        {
            'id': 1,
            'data': 'example',
        },
        {
            'id': 2,
            'data': 'example2',
        }
    ]
}

• count contains the number of items in total
• If the current page is not the last one, next will contain the url of the next page
• If the current page is not the first one, previous will contain the url of the previous page

Here is a code example in Python where we go through every page to fetch all the data contained in an api endpoint:

import requests

USERNAME = 'james_watson'
PASSWORD = 'ilovesherlock'
url = 'https://homelocpay.net/api_endpoint/'
auth = (USERNAME, PASSWORD)

all_results = []
while True:
    r = requests.get(auth=auth, url)
    r = r.json()
    results = r.get('results', [])
    next = r.get('next')
    all_results += results
    if not next:
        break
    url = next

print all_results