@alejandro.devop/react-json-api-client

Index

• Installation
• Usage
• HttpClient
• Types
• Glosary

Installation

yarn add @alejandro.devop/react-json-api-client

Usage

1. Define a file where you will include your endpoints a. The <post> rule specifies that the endpoint should be only called using this http method, but remember, the rule is not mandatory b. The :id: indicates a token which can be replace it when you call this endpoint

Note: The maximum nested level should be two

@config/endpoints.json

{
    "auth": {
        "login": "<post>/api/v1/security/auth",
        "logout": "<post>/api/v1/security/logout"
    },
    "users": {
        "active": "<post>/api/v1/security/users/:id:/inactive",
        "changePassword": "<post>/api/v1/security/users/:id:/changePassword",
        "create": "<post>/api/v1/security/users",
    },
    "roles": {
        "list": "<get>/api/v1/security/roles"
    }
}

2. Add the api configurator wraping the components which will have access to the http client. app.tsx

import React from 'react'
import ApiClientConfigurator from '@alejandro.devop/react-json-api-client'
import endpoints from '@config/endpoints.json'

const App: React.FC = () => {
    return (
        <ApiClientConfigurator
            config={{
                server: 'https://my-server',
                endpoints
            }}
        > 
            <>{/* my application navs... */}</>
        </ApiClientConfigurator>
    )
}

export default App

3. Use the provided hooks to make http requests

Types

MimeType

Description: Mime type for the request audio/aac application/x-abiword application/octet-stream video/x-msvideo application/vnd.amazon.ebook application/vnd.api+json application/octet-stream application/x-bzip application/x-bzip2 application/x-csh text/css text/csv application/msword application/epub+zip image/gif text/html image/x-icon text/calendar application/java-archive image/jpeg application/javascript application/json audio/midi video/mpeg application/vnd.apple.installer+xml application/vnd.oasis.opendocument.presentation application/vnd.oasis.opendocument.spreadsheet application/vnd.oasis.opendocument.text audio/ogg video/ogg application/ogg application/pdf application/vnd.ms-powerpoint application/x-rar-compressed application/rtf application/x-sh image/svg+xml application/x-shockwave-flash application/x-tar image/tiff font/ttf application/vnd.visio audio/x-wav audio/webm video/webm image/webp font/woff font/woff2 application/xhtml+xml application/vnd.ms-excel application/xml application/vnd.mozilla.xul+xml application/zip video/3gpp video/3gpp2 application/x-7z-compressed

HeaderType

Description: Specifies the type for the headers

{
    Accept?: MimeType
    'Accept-Ranges'?: number
    Age?: string
    Authorization?: string
    'Cache-control'?: string
    'Content-Length'?: number
    'Content-Type'?: MimeType
    Connection?: string
    Date?: string
    ETag?: string
    Expires?: string
    'Last-Modified'?: string
    Server?: string
    Via?: string
}

AvailablePropertiesType

Description: Specifies the properties for the method addProperties

{headers?: HeaderType; auth?: string}

EndpointDefinitionType

Description: Defines structure for the endpoints object

type SingleEndpointType = {
    [k: string]: string | { [k: string]: SingleEndpointType }
}

type EndpointDefinitionType = {
    [k: string]: SingleEndpointType
}

RequestBodyType

Description Defines the type for the request response

Generics |Name|Description| |:--|:--| |RequestBodyDefType|Defines the payload type|

type RequestBodyType<RequestBodyDefType extends Object = {}> =
    | {data?: RequestBodyDefType}
    | RequestBodyDefType

ResolveUrlConfigType

Description Configuration for the url replacer

Note: Usually a JSON api handles the pagination, filters and sorts in the url schema. Check https://jsonapi.org/ for more information

Generics |Name|Description| |:--|:--| |OptionalReplace|Specify the replacement type| |FilterOverride| Specify the filter type|

type ReplacementValueType = 'string' | number | boolean

type ResolveUrlConfigType<OptionalReplace = any, FilterOverride = any> = {
    /** Key/Value used to replace tokens in url */
    replacements?: {[k: string]: ReplacementValueType & OptionalReplace}
    /** Character(s) used to define tokens */
    replaceToken?: string
    /** Pagination records per page */
    pageSize?: number
    /** Current page */
    currentPage?: number
    /** Sorts criteria */
    sorts?: string[]
    /** key/value used to define filters in url */
    filters?: {[k: string]: FilterType & FilterOverride}
}

MethodType

Description Methods available for the http client

export type MethodType = 'get' | 'post' | 'patch' | 'put' | 'delete'

RequestConfigType

Description Configuration for common requests

Generics |Name|Description| |:--|:--| |ParamType| Specify the url params type, used for the url replacer|

type RequestConfigType<ParamsType extends Object = {}> = {
    /** Provide content for the authorization header */
    auth?: string
    /** Whether the client should debug the request */
    debug?: boolean
    /** Method to be used on the request */
    method?: MethodType
    /** Custom params for the url */
    params?: {[k: string]: ParamsType}
    /** Custom header for the request */
    headers?: HeaderType
    /** Axios response type */
    responseType?: AxiosResponseType
}

RequestConfigWithPayloadType

Description Configuration for requests with payload post patch put

Generics |Name|Description| |:--|:--| |PayloadType|Specify payload type|

type RequestConfigWithPayloadType<PayloadType = {}> = RequestConfigType<{
    [k: string]: any
}> & {
    /** Payload to be sent with the request */
    payload?: PayloadType
}

DoRequestResponseType

Description Specifies the doRequest method response structure

Generics |Name|Description| |:--|:--| |CustomResponseType|Specifies the structure for the data position|

type DoRequestResponseType<CustomResponseType extends Object = {}> = {
    status: number
    request: {
        url: string
        server: string
    }
    data?: CustomResponseType | null
    error?: boolean
    info?: any
}

DataProcessorType

Description Defines type for dataProcessors

Generics |Name|Description| |:--|:--| |DataInType|Specifies the type for the incomming data| |DataOutType|Specifies the type for the output data|

type DataProcessorType<DataInType, DataOutType> = (
    d: DataInType,
) => DataOutType

HttpClientType

Description HttpClient instance type

Generics |Name|Optional|Description| |:--|:--|:--| |DPIn|yes|Specifies the type for the dataprocessor incomming data| |DPOut|yes|Specifies the type for the output data|

type HttpClientType<
    DPIn extends Object = {},
    DPOut extends Object = {},
> = {
    auth?: string
    server: string
    endpoints: EndpointDefinitionType
    dataProcessor?: DataProcessorType<DPIn, DPOut>
    headers?: HeaderType
    processData?: DataProcessorType<any, any>
    onRequestDone?: (data: any) => void
}

ResponseType

Description Specifies the return type for the api response call Generics |Name|Description| |:--|:--| |ResponseDefType|Definition for the response object|

type ResponseType<ResponseDefType extends object = {}> =
    | {data: ResponseDefType}
    | ResponseDefType

Glosary

dataProcessors

Is a function used to process o reorganize the response sended by the api, if you need to re-structure the response data processors is what you need

Url replacer

Is the process of creating a url, the client builds a url using a replacement method which takes the params.