Crate ciboulette

Introduction

Ciboulette is a JSON:API library.

It allows one to parse request and build response respecting the JSON:API specifications.

It aims to have a low memory footprint and be fast.

High level view of components

At a high level, an API is constitued of resource types. The resource type are organized in a graph representing their relationships as edges.

In addition to the graph, an adgacent map is used to efficiently retrieve resource types by their alias. This whole structure is held in a store.

Resource types

The resource types can be built using a resource type builder. It’s made of :

• A name, that will later be used as an alias to fetch the resource types from the store’s graph.
• A id type, which will be used to deserialize the ids the requests.
• A schema which will be used to deserialize the body of the requests and serialize the response.

Relationship options

Many-to-Many

The option struct map a resource “A” to another resource “C” through another resource “B” (bucket)

    Resource A                      Resource B (bucket)                    Resource C
┌─────────────────┐  ┌─────────────────────────────────────────────┐  ┌─────────────────┐
│                 │  │                                             │  │                 │
│  peoples──►id───┼──┼──►people_id◄──people-article──►article_id◄──┼──┼──id◄──articles  │
│                 │  │                                             │  │                 │
└─────────────────┘  └─────────────────────────────────────────────┘  └─────────────────┘

When creating a Many-to-Many relationships (A <-> C), we’ll also create a Many-to-One relationship between the table A -> B, C -> B, B -> A and B -> C so that we can reference the relationship directly.

One-to-Many / Many-to-One

The option struct map a “many” resource to a “one” resource.

                    Many table                                          One table
┌──────────────────────────────────────────────────┐  ┌──────────────────────────────────────┐
│                                                  │  │                                      │
│ many_table_element_0──────────►many_table_key_0──┼──┼──►one_table_id◄───one_table_element  │
│                                                  │  │     ▲      ▲                         │
│                                                  │  │     │      │                         │
│ many_table_element_1──────────►many_table_key_1──┼──┼─────┘      │                         │
│                                                  │  │            │                         │
│                                                  │  │            │                         │
│ many_table_element_2──────────►many_table_key_2──┼──┼────────────┘                         │
│                                                  │  │                                      │
│                                                  │  └──────────────────────────────────────┘
└──────────────────────────────────────────────────┘

In the option a field is used to determined if a Many-to-One/One-to-Many relationship is part of Many-to-Many relationship.

Requests

Every requests boils down to the same components. But there is some quirks :

• Creation request can be valid without resource id,
• Update request can have a body of resource identifier.

Every requests must first be deserialized using the request builder. Then it can be built into an generic request. From that, one can convert to the desired request type depending on the intention. Trying to convert a generic request to an incompatible sub-type will result in an error. The correct conversion map goes like this :

Intention	Request type
Create	Create request
Read	Read request
Update	Update request
Delete	Delete request

Every sub-type of requests implement a common trait to allow for genericity.

Responses

A response is built from a request and a list of response element.

Depending on the request, the response will be built to the correct format.

Response elements

Each response should have a single main resource type.

The response elements are composed as follow for an element part of the main resource type:

Response element field	Always required	Description
type	✅	The current element resource type
identifier	✅	The current element resource identifier
data	❌	The JSON data of the resource, if any
related.rel_chain	❌ (only for related data)	Chain of relation metadata from the main resource type
related.element	❌ (only for related data)	The resource identifier of the element it relates to

Structs

CibouletteBody	A json:api document object
CibouletteBodyBuilder	Builder object for CibouletteBody
CibouletteBodyLink	A json:api top-level link object with pagination support
CibouletteBodyPagination	A json:api top-level link object with pagination support
CibouletteConfig	Ciboulette configuration
CibouletteCreateRequest	A POST request
CibouletteDeleteRequest	A DELETE request
CibouletteErrorLink	A link describing a json:api error
CibouletteErrorObj	Object of a json:api error
CibouletteErrorRequest	An outbound response, built from an inbound request.
CibouletteErrorSource	Source object of a json:api error
CibouletteJsonApiVersion	Object holder json:api version
CibouletteLink	A json:api link object
CibouletteLinkObj	A json:api inner link object
CibouletteQueryParameters	Query parameters for json:api
CibouletteQueryParametersBuilder	Builder object for CibouletteQueryParameters
CibouletteReadRequest	A ‘GET’ request
CibouletteRelationshipManyToManyOption	Many-to-Many relationships options
CibouletteRelationshipManyToManyOptionBuilder	Many-to-Many relationships option builder
CibouletteRelationshipObject	A json:api relationship object
CibouletteRelationshipObjectBuilder	Builder for CibouletteRelationshipObject
CibouletteRelationshipOneToManyOption	One-to-Many/Many-to-One relationships options
CibouletteRelationshipOneToManyOptionBuilder	One-to-Many/Many-to-one relationships option builder
CibouletteRequest	Abstract representation of a JSON:API request
CibouletteRequestBuilder	Builder object for CibouletteBody
CibouletteResource	A json:api resource object
CibouletteResourceBuilder	Builder object for CibouletterResource
CibouletteResourceIdentifier	A json:api resource identifier object
CibouletteResourceIdentifierBuilder	Builder for resource identifier
CibouletteResourceIdentifierPermissive	A json:api resource identifier object
CibouletteResourceRelationshipDetails	Relationships metadata for CibouletteResourceType
CibouletteResourceResponseIdentifier	A json:api resource identifier object
CibouletteResourceResponseIdentifierBuilder	Builder for CibouletteResourceResponseIdentifier
CibouletteResourceType	Describe a json:api type attribute schema and list its relationships
CibouletteResourceTypeBuilder	Describe a json:api type attribute schema and list its relationships
CibouletteResponse	A response, built from a request.
CibouletteResponseBody	JSON:API response body
CibouletteResponseDataBuilder	A builder structure for CibouletteOutboundRequest
CibouletteResponseElement	Container for response element.
CibouletteResponseRelationshipObject	Relationships object included in a response
CibouletteResponseResource	Resource included in a response
CibouletteSortingElement	Element of a sorting list.
CibouletteStore	Map of accepted resource types
CibouletteStoreBuilder	Builder for CibouletteStore
CibouletteUpdateRelationshipBody	Body of a relationships update request
CibouletteUpdateRequest	An UPDATE request

Enums

CibouletteClashDirection	When describing KeyClash, we need to know if the field was supposed be with or without another field
CibouletteError	An error throwable by Ciboulette
CibouletteId	Resource id type
CibouletteIdSelector	Resource id type selector
CibouletteIdType	Type of resource id
CibouletteIdTypeSelector	Type of resource id
CibouletteIntention	Represent the client intention (request method) when sending the request
CibouletteOptionalData	Wrapper for optional data
CiboulettePageType	The page type used in the CibouletteQueryParametersField
CiboulettePath	Path of a JSON:API request
CiboulettePathBuilder	Path builder for JSON:API requests
CiboulettePathType	JSON:API Path type
CibouletteRelationshipOption	Relationships options
CibouletteRelationshipOptionBuilder	Relationship options builder
CibouletteRequestSelector	Builder object for CibouletterResourceSelector
CibouletteResourceIdentifierSelector	A selector between a single or multiple json:api resource identifier objects
CibouletteResourceIdentifierSelectorBuilder	A selector for resource identifier, to either select one or many resource identifiers
CibouletteResourceResponseIdentifierSelector	A selector between a single or multiple json:api resource identifier objects
CibouletteResourceResponseIdentifierSelectorBuilder	Selector for CibouletteResourceResponseIdentifierSelectorBuilder
CibouletteResourceSelector	A selector between a single or multiple json:api resource objects
CibouletteResourceSelectorBuilder	Builder object for CibouletterResourceSelector
CibouletteResponseQuantity	The quantity of data that should be returned
CibouletteResponseRequiredType	The format the return object should have
CibouletteResponseResourceSelector	Selector for CibouletteResponseResource
CibouletteResponseStatus	The status a response should send
CibouletteSortingDirection	Direction for sorting element
CibouletteUpdateRequestType	Update request type

Traits

CibouletteRequestCommons

JSON:API inbound requests

Functions

check_member_name

Type Definitions

CibouletteBodyData
CibouletteBodyDataBuilder
CibouletteBodyDataPermissive
CibouletteResponseBodyData