Crate ciboulette

Expand description

§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 Aliases§

CibouletteBodyData
CibouletteBodyDataBuilder
CibouletteBodyDataPermissive
CibouletteResponseBodyData