API Reference Resourceful v0.1.5

modules

Modules

Resourceful is a library intended to provide a common interface for generic operations and representations for resources in an edge-facing API. These include

Provides a common interface for querying and retrieving collections.

Functions for converting Resourceful-style filters into Ecto-style SQL filters.

Provides a common interface for filtering collections. See call/2 for use and examples.

Provides a common interface for sorting collections. See call/2 for use and examples.

Errors in Resourceful follow a few conventions. This module contains functions to help work with those conventions. Client-facing errors are loosely inspired by and should be easily converted to JSON:API-style errors, however they should also be suitable when JSON:API isn't used at all.

Tools for converting errors formatted in accordance with Resourceful.Error into JSON:API-style errors.

Functions for validating fields, primarily for use with JSON:API sparse fieldsets. Fields are provided by type type_name in requests and not inferred from root or relationship names. This means that if a type has multiple relationships pointing to a single type or a self-referential relationships, these will be applied to all instances of that type type_name regardless of its location in the graph.

Functions for validating includes, primarily for use with JSON:API inclusion of related resources.

Validates parameters provided by various pagination strategies and returns paramaters as expected by Resourceful.Collection.

Functions for converting URL parameters into Resourceful queries. Additionally validates parameters when JSON:API-specific parameters are provided such as fields.

Resourceful.Type is a struct and set of functions for representing and mapping internal data structures to data structures more appropriate for edge clients (e.g. API clients). As a result, field names are always strings and not atoms.

Attributes represent "value" fields for a given Resourceful.Type. This governs a few common operations

Functions for import in Resourceful.Registry for building types programmatically.

Creates a Resourceful.Type from an Ecto.Schema module. The use case is that internal data will be represented by the schema and client-facing data will be represented by the resource definition. Additionally, field names may be mapped differently to the client, such as camel case values. This can be done individually or with a single function as an option.

This module is something of hack designed to deal with the fact that Ecto does not make it simple to

A graphed field is a field (an attribute or a relationship) bundled with graph data dictating how it is to be mapped in a graph from the perspective of a type.

Relationships come in one of two types: :one or :many. Things like foreign keys and how the relationships map are up to the underlying data source. For the purposes of mapping things in Resourceful, it simply needs to understand whether it's working with a single thing or multiple things.

Extra utility functions. These are for miscellaneous shared functions that don't really fit with any other module but are shared across multiple modules.