Crate ciboulette

Source
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 :

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 fieldAlways requiredDescription
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