Upgrade guide

This document will guide you through upgrading from apiron 2.X versions to apiron 3.X.

Replacing ServiceCaller usage

As of version 2.3.0, instantiating a service class and passing it to ServiceCaller.call is no longer necessary. In 3.X, ServiceCaller has been removed altogether (though its behaviors are still in the apiron.client module). Replace calls to ServiceCaller.call with the more semantic SomeService.some_endpoint:

# Before
from apiron.client import ServiceCaller
from apiron.service.base import Service
from apiron.endpoint import JsonEndpoint

class GitHub(Service):
    domain = 'https://api.github.com'
    user = JsonEndpoint(path='/users/{username}')
    repo = JsonEndpoint(path='/repos/{org}/{repo}')

GITHUB = GitHub()

defunkt = ServiceCaller.call(GITHUB, GITHUB.user, path_kwargs={'username', 'defunkt'})


# After
from apiron.service.base import Service
from apiron.endpoint import JsonEndpoint

class GitHub(Service):
    domain = 'https://api.github.com'
    user = JsonEndpoint(path='/users/{username}')
    repo = JsonEndpoint(path='/repos/{org}/{repo}')

defunkt = GitHub.user(path_kwargs={'username', 'defunkt'})

Simplifying imports

As of version 2.4.0, most classes are available as top-level imports from the apiron package:

# Before
from apiron.service.base import Service
from apiron.endpoint import JsonEndpoint

# After
from apiron import Service, JsonEndpoint

Simplifying endpoint path placeholders

As of version 2.5.0, path_kwargs is no longer necessary; just pass path fillers as additional keyword arguments:

# Before
defunkt = GitHub.user(path_kwargs={'username', 'defunkt'})

# After
defunkt = GitHub.user(username='defunkt')

Summary

Prepare for apiron 3.X by installing apiron 2.5+ and doing the following:

  • Replace ServiceCaller.call with the more direct SomeService.some_endpoint
  • Import classes from apiron directly
  • Replace path_kwargs with direct keyword arguments