API

sandman2 provides a minimal API to control the behavior and inclusion of resources from the database.

sandman2’s main module.

class sandman2.model.Model

The sandman2 Model class is the base class for all RESTful resources. There is a one-to-one mapping between a table in the database and a sandman2.model.Model.

__methods__ = {'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT'}

The HTTP methods this resource supports (default=all).

__url__ = None

The relative URL this resource should live at.

__version__ = '1'

The API version of this resource (not yet used).

classmethod description()

Return a field->data type dictionary describing this model as reported by the database.

Return type:dict

links()

Return a dictionary of links to related resources that should be included in the Link header of an HTTP response.

Return type:dict

classmethod optional()

Return a list of all nullable columns for the resource’s table.

Return type:list

classmethod primary_key()

Return the key of the model’s primary key field.

Return type:string

classmethod required()

Return a list of all columns required by the database to create the resource.

Parameters:cls – The Model class to gather attributes from Return type:list

resource_uri()

Return the URI to this specific resource.

Return type:str

to_dict()

Return the resource as a dictionary.

Return type:dict

update(attributes)

Update the current instance based on attribute->value items in attributes.

Parameters:attributes (dict) – Dictionary of attributes to be updated Return type:sandman2.model.Model

class sandman2.service.Service

The Service class is a generic extension of Flask’s MethodView, providing default RESTful functionality for a given ORM resource.

Each service has an associated __model__ attribute which represents the ORM resource it exposes. Services are JSON-only. HTML-based representation is available through the admin interface.

delete(resource_id)

Return an HTTP response object resulting from a HTTP DELETE call.

Parameters:resource_id – The value of the resource’s primary key

get(resource_id=None)

Return an HTTP response object resulting from an HTTP GET call.

If resource_id is provided, return just the single resource. Otherwise, return the full collection.

Parameters:resource_id – The value of the resource’s primary key

methods = {'DELETE', 'GET', 'PATCH', 'POST', 'PUT'}

patch(resource_id)

Return an HTTP response object resulting from an HTTP PATCH call.

Returns:HTTP 200 if the resource already exists Returns:HTTP 400 if the request is malformed Returns:HTTP 404 if the resource is not found Parameters:resource_id – The value of the resource’s primary key

post()

Return the JSON representation of a new resource created through an HTTP POST call.

Returns:HTTP 201 if a resource is properly created Returns:HTTP 204 if the resource already exists Returns:HTTP 400 if the request is malformed or missing data

put(resource_id)

Return the JSON representation of a new resource created or updated through an HTTP PUT call.

If resource_id is not provided, it is assumed the primary key field is included and a totally new resource is created. Otherwise, the existing resource referred to by resource_id is updated with the provided JSON data. This method is idempotent.

Returns:HTTP 201 if a new resource is created Returns:HTTP 200 if a resource is updated Returns:HTTP 400 if the request is malformed or missing data

The sandman2.exception module contains an Exception, expressible in JSON, for each HTTP status code. In general, code should raise these exceptions directly rather than making a call to Flask’s abort() method.

JSON-based Exception classes which generate proper HTTP Status Codes.

exception sandman2.exception.BadRequestException(message=None, payload=None)

Raised when a request contains illegal arguments, is missing arguments, can’t be decoded properly, or the request is trying to do something that doesn’t make sense.

code = 400

exception sandman2.exception.ConflictException(message=None, payload=None)

Similar to a ServerErrorException (HTTP 500) but there is some action the client may take to resolve the conflict, after which the request can be resubmitted. A request to reprocess a job not marked for reprocessing, for example, could cause this exception to be raised.

code = 409

exception sandman2.exception.EndpointException(message=None, payload=None)

Base class for all Exceptions.

to_dict()

Return a dictionary representation of the exception.

exception sandman2.exception.ForbiddenException(message=None, payload=None)

Raised when a request asks us to do something that we won’t do because it violates the application logic. Does not refer to an authentication failure. Rather, it means the action requested is forbidden by the application.

code = 403

exception sandman2.exception.NotAcceptableException(message=None, payload=None)

Raised when the client does not Accept any of the Content-Types we are capable of generating.

code = 406

exception sandman2.exception.NotFoundException(message=None, payload=None)

Raised when the endpoint (or a resource it refers to) is not found. Can also be used if a resource referred to in a request (e.g. a specific job in a /job_status request) can not be found.

code = 404

exception sandman2.exception.NotImplementedException(message=None, payload=None)

Raised when the application does not implement the functionality being requested. Note that this doesn’t refer to an HTTP method not being implemented for a given endpoint (which would be a 405 error).

code = 501

exception sandman2.exception.ServerErrorException(message=None, payload=None)

Raised when the application itself encounters an error not related to the request itself (for example, a database error).

code = 500

exception sandman2.exception.ServiceUnavailableException(message=None, payload=None)

Raised when a resource is temporarily unavailable (e.g. not being able to get a database connection). Setting the Retry-After header gives the length of the delay, if it is known. Otherwise, this is treated as a 500 error.

code = 503

Indices and tables

• Index
• Module Index
• Search Page