Kinto / elm-kinto / Kinto

Kinto client to ease communicating with the REST API.

Kinto is the backend for your next application. It's a generic JSON document store with sharing and synchronisation capabilities. It's open source. It's easy to deploy. You can host it yourself, own your data and keep it out of silos.

Configure a client and resources


type alias Client =
{ baseUrl : String
, headers : List ( String
, String ) 
}

A Kinto Client. Constructed using the client helper.

client : Url -> Auth -> Client

A constructor for a Client.

client
    "https://kinto.dev.mozaws.net/v1/"
    (Basic "username" "password")


type Auth
    = NoAuth
    | Basic String String
    | Bearer String
    | Custom String String

A type for authentication

Basic "username" "password"

Bearer "<token>"

Custom "customType" "customString"

headersForAuth : Auth -> ( String, String )

Return the header name and value for the given Auth.

headersForAuth (Basic "username" "password")


type alias Resource a =
{ itemEndpoint : String -> Endpoint
, listEndpoint : Endpoint
, itemDecoder : Json.Decode.Decoder a
, listDecoder : Json.Decode.Decoder (List a) 
}

A type for a Kinto resource. Usually constructed using one of bucketResource, collectionResource or recordResource.

bucketResource : Json.Decode.Decoder a -> Resource a

A constructor for a bucket resource.

bucketResource bucketDecoder

collectionResource : BucketName -> Json.Decode.Decoder a -> Resource a

A constructor for a collection resource.

collectionResource "bucket-name" collectionDecoder

recordResource : BucketName -> CollectionName -> Json.Decode.Decoder a -> Resource a

A constructor for a record resource.

decodeData : Json.Decode.Decoder a -> Json.Decode.Decoder a

A decoder for a basic Kinto response.

encodeData : Json.Encode.Value -> Json.Encode.Value

An encoder for a basic Kinto query.

errorDecoder : Json.Decode.Decoder ErrorDetail

A decoder for ErrorDetail. This is the kind of json message answered by Kinto when there's an error:

{"errno":104,
 "message":"Please authenticate yourself to use this endpoint.",
 "code":401,
 "error":"Unauthorized"}

errorToString : Error -> String

Convert any Kinto.Error to a string

Creating requests

You create requests on either an item or a plural (list) endpoint. Kinto concepts explain that in details.

Plural (list) endpoints are:

Item endpoints are:


type alias Request a =
HttpBuilder.RequestBuilder a

A type describing a Kinto request. Basically an alias for an elm-http-builder request builder.

withQueryParam : ( String, String ) -> Request a -> Request a

Update the URL to add a query parameter.

Single item requests

get : Resource a -> String -> (Result Error a -> msg) -> Client -> Request msg

Create a GET request on an item endpoint

client
    |> get resource itemId

create : Resource a -> Body -> (Result Error a -> msg) -> Client -> Request msg

Create a POST request on a plural endpoint:

client
    |> create resource itemId data

update : Resource a -> String -> Body -> (Result Error a -> msg) -> Client -> Request msg

Create a PATCH request on an item endpoint:

client
    |> update resource itemId data

replace : Resource a -> String -> Body -> (Result Error a -> msg) -> Client -> Request msg

Create a PUT request on an item endpoint:

client
    |> replace resource itemId data

delete : Resource a -> String -> (Result Error a -> msg) -> Client -> Request msg

Create a DELETE request on an item endpoint:

client
    |> delete resource itemId

Resource list requests

getList : Resource a -> (Result Error (Pager a) -> msg) -> Client -> Request msg

Create a GET request on one of the plural endpoints. As lists are always possibly paginated, When the request is succesful, a Pager is attached to the reponse message.

client
    |> getList resource

count : Resource a -> (Result Error Basics.Int -> msg) -> Client -> Request msg

Count the number of records within a given collection

client
    |> count resource CountReceived

Paginated list


type alias Pager a =
{ client : Client
, objects : List a
, decoder : Json.Decode.Decoder (List a)
, nextPage : Maybe Url 
}

A stateful accumulator for a paginated list of objects.

Note: as of 8.0.0, the total field has been removed from the record. You must use the count function to retrieve the total number of records.

emptyPager : Client -> Resource a -> Pager a

Initialize a Pager.

emptyPager resource

updatePager : Pager a -> Pager a -> Pager a

Update a previous pager with data from a new one, appending new objects to the previous list.

updatePager nextPager previousPager

loadNextPage : Pager a -> (Result Error (Pager a) -> msg) -> Maybe (Request msg)

If a pager has a nextPage, creates a GET request to retrieve the next page of objects. When the request is succesful, a Pager with new objects appended is attached to the reponse message.

client
    |> loadNextPage pager

Sorting, limiting, filtering

sort : List String -> Request a -> Request a

Add sorting query parameters to the request sent to the Kinto server.

type Msg = TodosFetched (Result Kinto.Error (Kinto.pager Todo))

client
    |> getList recordResource
    |> sort ["title", "description"]
    |> send TodosFetched

limit : Basics.Int -> Request a -> Request a

Add limit query parameters to the request sent to the Kinto server.

type Msg = TodosFetched (Result Kinto.Error (Kinto.pager Todo))

client
    |> getList recordResource
    |> limit 10
    |> send TodosFetched

filter : Filter -> Request a -> Request a

Add filtering query parameters to the request sent to the Kinto server.

type Msg = TodosFetched (Result Kinto.Error (Kinto.pager Todo))

client
    |> getList recordResource
    |> filter (NOT "title" "test")
    |> send TodosFetched


type Filter
    = EQUAL String String
    | MIN String String
    | MAX String String
    | LT String String
    | GT String String
    | IN String (List String)
    | NOT String String
    | LIKE String String
    | SINCE String
    | BEFORE String

A type for filtering, used with filter

Types and Errors


type Endpoint
    = RootEndpoint
    | BucketListEndpoint
    | BucketEndpoint BucketName
    | CollectionListEndpoint BucketName
    | CollectionEndpoint BucketName CollectionName
    | RecordListEndpoint BucketName CollectionName
    | RecordEndpoint BucketName CollectionName RecordId

A type for Kinto API endpoints.

RecordEndpoint "bucket-name" "collection-name" "item-id"

endpointUrl : String -> Endpoint -> Url

Get the full url to an endpoint.

endpointUrl "https://kinto.dev.mozaws.net/v1/" (RecordListEndpoint "default" "test-items")


type alias ErrorDetail =
{ errno : Basics.Int
, message : String
, code : Basics.Int
, error : String 
}

A type for Kinto error details.


type Error
    = ServerError StatusCode StatusMsg String
    | KintoError StatusCode StatusMsg ErrorDetail
    | NetworkError (Http.Response String)

A type for all errors that the elm-client may return.

expectJson : (Result Error a -> msg) -> Json.Decode.Decoder a -> Http.Expect msg

Extract an Error from an Http.Error or return the decoded value.

expectPagerJson : (Result Error (Pager a) -> msg) -> Client -> Json.Decode.Decoder (List a) -> Http.Expect msg

Extract an Error from an Http.Error or return a Pager for the decoded list.

Sending requests

send : Request a -> Platform.Cmd.Cmd a

Send a request to the Kinto server.

type Msg = TodoAdded (Result Kinto.Error Todo)

client
    |> create resource data
    |> send TodoAdded