API Relational Model

Build API requests using an ORM-style abstraction layer

The API Relational Model has not been implemented in all libraries yet.

API Relational Model, or ARM, is a software library abstraction of the underlying API resources in much the same way ORMs abstract database requests. ARM combines functionality like the query language, attribute functions, and object attribute selection. The ARM representations are then compiled into API requests and executed.

Example ARM Request

Here's an example ARM request for monthly aging receivables:

arm.py

import payload
from datetime import datetime, timedelta
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# An ARM api request representation
# requesting monthly aging receivables
 
 
results = pl.Invoice.select(
        pl.attr.due_date.month(),
        pl.attr.due_date.year(),
        pl.attr.amount_due.sum()
    ).filter_by(
        pl.attr.status == 'overdue',
        pl.attr.due_date <= datetime.now() - timedelta(days=30)
    ).group_by(
        pl.attr.due_date.month(),
        pl.attr.due_date.year()
    ).all()

The `attr` Object

The attr object is a dot notation interface for any object attributes. Attribute functions can be called as methods of the attributes.

Example Usage

attr.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Access attributes using dot notation
 
 
pl.attr.customer_id
pl.attr.amount
pl.attr.created_at
 
# Call functions on attributes
pl.attr.email.lower()
pl.attr.amount.sum()
pl.attr.created_at.year()

Using `select` to Select Attributes

The select class method can be used to specify what attributes you want in your API response. Below are the common ways to use select:

Get Additional Attributes

select can be used to request additional attributes that are not included by default for the object (more details on these additional attributes can be found in the Object Reference). To request all default attributes for an object, use *pl.Transaction wildcard operator.

additional.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Request all default attributes plus additional ones
 
 
results = pl.Transaction.select(
    *pl.Transaction,  # All default attributes
    pl.attr.processing_details  # Additional attribute
).all()

Select Specific Attributes

Return a specific set of attributes by passing the desired attributes as parameters to select.

specific.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Select only specific attributes
 
 
results = pl.Account.select(
    pl.attr.id,
    pl.attr.email,
    pl.attr.name
).all()

Calling Functions

Use a function to modify the value of an attribute passed to select by calling the method on the attr representation being passed to select.

functions.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Apply functions to attributes
 
 
results = pl.Account.select(
    pl.attr.email.lower(),
    pl.attr.created_at.year(),
    pl.attr.name.upper()
).all()

Querying with `filter_by`

To filter the results of an API request, you can construct conditional statements with attr attributes and pass those to filter_by. filter_by uses lazy-loading and does not execute API requests immediately letting you chain filter_by calls or other non-terminal methods.

Example Filters

filter.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Simple equality filter
 
 
customers = pl.Account.filter_by(
    pl.attr.status == 'active'
).all()
 
# Multiple conditions
payments = pl.Transaction.filter_by(
    pl.attr.amount > 100,
    pl.attr.status == 'processed'
).all()
 
# Complex conditions with OR
risky_payments = pl.Transaction.filter_by(
    (pl.attr.risk_status == 'denied') | (pl.attr.risk_status == 'in_review')
).all()

Executing the Request

Requests aren't immediately executed when using select, filter_by, and group_by. Requests wait for an execution trigger method or are iterated. The ways in which a request execution is triggered are by using method all, first, update, or delete. Request execution is also triggered by iterating over the request or slicing the request results.

Execution Methods

.all() - Returns all matching results
.first() - Returns the first matching result
.update(data) - Updates all matching results
.delete() - Deletes all matching results

Iteration and Slicing

iterate.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Iteration triggers execution
 
 
for customer in pl.Account.filter_by(pl.attr.status == 'active'):
    print(customer.name)
 
# Slicing triggers execution
first_10_customers = pl.Account.order_by(pl.attr.created_at).limit(10).all()

ARM Method Chaining

ARM supports method chaining to build complex queries:

chaining.py

from datetime import datetime, timedelta
 
import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Complex chained query
 
 
results = (
    pl.Invoice.select(
        pl.attr.customer_id,
        pl.attr.amount_due.sum(),
    )
    .filter_by(
        pl.attr.status == 'overdue',
        pl.attr.due_date < datetime.now(),
    )
    .group_by(pl.attr.customer_id)
    .order_by(pl.attr.amount_due.desc())
    .all()
)

Hierarchical Object Design Transaction