Upgrading

Upgrading from 0.6.0 to 0.7.0

Eve-SQLAlchemy is now based on Eve 0.7, which introduces potentially breaking changes:

  • The ETag format was changed to comply with RFC 7232-2.3. Be aware the ETag header values are now enclosed with double-quotes.
  • Eve now returns a 428 Precondition Required instead of a generic 403 Forbidden when the If-Match request header is missing.

For a comprehensive list of changes refer to the official changelog.

Upgrading from 0.5.0 to 0.6.0

There is one potentially breaking change in 0.6.0: Due to a regression 0.5.0 did not return None/null values anymore (as Eve does and 0.4.1 did). That means your API might return slightly different responses after upgrading to 0.6.0 than it did before. If it’s really a breaking change for you depends on your API specification and your clients.

Upgrading from 0.4.1 to 0.5.0

There are two breaking changes in 0.5.0:

  1. Eve-SQLAlchemy now handles related IDs and embedded objects with just one field in the payload, just as Eve does. This will most likely affect your consumers, too!
  2. We introduced a new way to register your SQLAlchemy models with Eve. So far there is no backward compatible wrapper for the former registerSchema decorator.

Let’s look at the needed changes in more detail. To illustrate both changes, we will look at the following models (the full code is in the examples directory):

class People(CommonColumns):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True, autoincrement=True)
    firstname = Column(String(80))
    lastname = Column(String(120))
    fullname = column_property(firstname + " " + lastname)


class Invoices(CommonColumns):
    __tablename__ = 'invoices'
    id = Column(Integer, primary_key=True, autoincrement=True)
    number = Column(Integer)
    people_id = Column(Integer, ForeignKey('people.id'))
    people = relationship(People, uselist=False)

2. Registering of SQLAlchemy models

In 0.4.1, you were most likely doing something along the following lines in your settings.py:

ID_FIELD = 'id'
config.ID_FIELD = ID_FIELD

registerSchema('people')(People)
registerSchema('invoices')(Invoices)

DOMAIN = {
    'people': People._eve_schema['people'],
    'invoices': Invoices._eve_schema['invoices']
}

There are good news: manually (and globally) setting ID_FIELD, including the workaround of setting config.ID_FIELD, is not required anymore. The same applies to ITEM_LOOKUP_FIELD and ITEM_URL. While you can still override them, they are now preconfigured at the resource level depending on your models’ primary keys.

The required configuration for the models above simplifies to:

from eve_sqlalchemy.config import DomainConfig, ResourceConfig

DOMAIN = DomainConfig({
    'people': ResourceConfig(People),
    'invoices': ResourceConfig(Invoices)
}).render()

Note: If you’ve modified DATE_CREATED, LAST_UPDATED or ETAG, you have to pass their value to DomainConfig.render(). They are needed during rendering the final DOMAIN configuration.

DomainConfig(domain_dict).render(date_created=DATE_CREATED,
                                 last_updated=LAST_UPDATED,
                                 etag=ETAG)