Elide JSON API Client

An opinionated {json:api} client for Elide based APIs

There are already a number of client libraries for working with JSON API, however this library is specifically designed for interacting with Elide based APIs, which has a few of it's own unique characteristics.

Features

Built with Typescript!
Built on top of axios as a peer dependency
Supports Promises and async/await
JSON API response normalization
- Flatter structure
- Merges included relationship data
Serializes normalized resources back to a JSON API structure
- Dates are converted to Unix epoch time for Elide
- Protected fields can be omitted from being sent to the API
Supports JSON Patch Extension for bulk writes and complex mutations
Parameter serialization
- Fields, filter, include, sort
- Pagination: size & number OR offset & limit
Request caching and throttling

Basic Usage

import ApiClient from 'elide-jsonapi-client'

// Initialize a new client
const api = new ApiClient({
  baseURL: 'http://localhost/api',
})

// Fetch a resource collection
const res = await api.fetch('articles')

// Create a resource
api.create('articles', {
  type: 'articles',
  title: 'Hello World',
})

// Update a resource
api.update('articles/1', {
  id: '1',
  type: 'articles',
  title: 'Hello World!!!',
})

// Remove a resource
api.remove('articles', 1)

Documentation

API Docs

Wiki

Credits

Inspired by Kitsu

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Ken White}
⚠️ 💻

This project follows the all-contributors specification. Contributions of any kind welcome! See CONTRIBUTING guidelines.

License

MIT

Index

Classes

ApiClient

Interfaces

Type aliases

Variables

Type aliases

Attribute

Attribute: string | number | boolean | object | undefined

Attribute of a Resource Object

ElideError

ElideError: { error: string; message: string; path: string; status: number; timestamp: string }

Errors

Type declaration

error: string
message: string
path: string
status: number
timestamp: string

NewResourceObject

NewResourceObject: { attributes?: Attributes; id?: undefined | string; links?: Links; relationships?: Relationships; type: string }

A representation of a new Resource Object that originates at the client and is yet to be created on the server. The main difference between a regular Resource Object is that this may not have an id yet.

Type declaration

Optional attributes?: Attributes
Optional id?: undefined | string
Optional links?: Links
Optional relationships?: Relationships
type: string

NormalizedResourceOrResources

NormalizedResourceOrResources: NormalizedResource | NormalizedResource[]

Operation

Operation: { op: OperationType; path: string; value: ResourceObject }

A Resource Operation

Type declaration

op: OperationType
path: string
value: ResourceObject

OperationType

OperationType: "add" | "remove" | "replace"

Operation Type constants

Operations

Operations: Operation[]

An array of Operations

PageParams

PageParams: { limit?: undefined | number; number?: undefined | number; offset?: undefined | number; size?: undefined | number; totals?: undefined | false | true }

Type declaration

Optional limit?: undefined | number
Optional number?: undefined | number
Optional offset?: undefined | number
Optional size?: undefined | number
Optional totals?: undefined | false | true

Params

Params: { fields?: string | Attributes; filter?: string | Attributes; include?: string | string[]; page?: undefined | number; pageSize?: undefined | number; sort?: string | string[] }

Parameters

Type declaration

Optional fields?: string | Attributes
Optional filter?: string | Attributes
Optional include?: string | string[]
Optional page?: undefined | number
Optional pageSize?: undefined | number
Optional sort?: string | string[]

RelationshipRef

RelationshipRef: { id: string; type: string }

Relationships

Type declaration

id: string
type: string

ResourceObject

ResourceObject: { attributes?: Attributes; id: string; links?: Links; relationships?: Relationships; type: string }

A representation of a single resource

Type declaration

Optional attributes?: Attributes
id: string
Optional links?: Links
Optional relationships?: Relationships
type: string

ResourceObjectOrObjects

ResourceObjectOrObjects: ResourceObject | ResourceObjects

Either or a single Resource Object or an array of Resource Objects

ResourceObjects

ResourceObjects: ResourceObject[]

An array of Resource Objects

SerializeOptions

SerializeOptions: { dateAttrs?: string[]; idRequired?: undefined | false | true; protectedAttrs?: string[] }

Options

Type declaration

Optional dateAttrs?: string[]
Optional idRequired?: undefined | false | true
Optional protectedAttrs?: string[]

SerializeParamsOptions

SerializeParamsOptions: { prefix?: undefined | false | true; size?: undefined | number; totals?: undefined | false | true; type?: undefined | string }

Type declaration

Optional prefix?: undefined | false | true
Optional size?: undefined | number
Optional totals?: undefined | false | true
Optional type?: undefined | string

Variables

Const ID_REQUIRED

ID_REQUIRED: "Resource must have an `id` property" = "Resource must have an `id` property"

Const ID_TYPE_REQUIRED

ID_TYPE_REQUIRED: "Relationship resource must have `id` and `type` properties" = "Relationship resource must have `id` and `type` properties"

Const JSON_API_CONTENT_TYPE

JSON_API_CONTENT_TYPE: "application/vnd.api+json" = "application/vnd.api+json"

Const JSON_API_PATCH_CONTENT_TYPE

JSON_API_PATCH_CONTENT_TYPE: "application/vnd.api+json; ext=jsonpatch" = "application/vnd.api+json; ext=jsonpatch"

Const TYPE_REQUIRED

TYPE_REQUIRED: "Resource must have a `type` property" = "Resource must have a `type` property"

Functions

Const concatUnique

concatUnique(...arr: any[]): never[]

- Defined in src/util.ts:61
Merge arrays while preserving only unique items

example

concatUnique([1,2], [2,3])

Parameters
- Rest ...arr: any[]
  
  array of primitives
Returns never[]

array of unique items, e.g. [1,2,3]

deserialize

deserialize(response: Response): Response<{ attributes?: Attributes; id: string; links?: Links; relationships?: Relationships; type: string } | { attributes?: Attributes; id: string; links?: Links; relationships?: Relationships; type: string }[]> | NormalizedResponse

- Defined in src/deserialize.ts:12
Deserializes a JSON API response into a normalized structure

Parameters
- response: Response
  
  A resource object or collection of object
Returns Response<{ attributes?: Attributes; id: string; links?: Links; relationships?: Relationships; type: string } | { attributes?: Attributes; id: string; links?: Links; relationships?: Relationships; type: string }[]> | NormalizedResponse

A normalized resource object or collection of objects

deserializeMutation

deserializeMutation(response: Response): (null | { id: string; type: string } | { errors: Error[] })[]

- Defined in src/deserializeMutation.ts:11
Deserializes a response from a JSON API PATCH request

Parameters
- response: Response
  
  A collection or response objects
Returns (null | { id: string; type: string } | { errors: Error[] })[]

A collection of normalized values

error

error(err: ApiError): void

- Defined in src/error.ts:9
Destructures an Axios response error

throws

The mutated Error

Parameters
- err: ApiError
  
  Request error response
Returns void

extractRelationships

extractRelationships(resource: ResourceObject): undefined | NormalizedRelationships

- Defined in src/normalize.ts:16
Hoists reltionship objects from the data property to a root level property

Parameters
- resource: ResourceObject
  
  A resource object
Returns undefined | NormalizedRelationships

A flattened relationship object

filterIncluded

filterIncluded(included: ResourceObject[], __namedParameters: { id: string; type: string }): { id: string; type: string } | { id: string; type: string } | { id: string; type: string } | { id: string; type: string }

- Defined in src/normalize.ts:38
Returns included relationship resources that match the provided relationship reference object

Parameters
- included: ResourceObject[]
  
  A collection of resource objects
- __namedParameters: { id: string; type: string }
  - id: string
  - type: string
Returns { id: string; type: string } | { id: string; type: string } | { id: string; type: string } | { id: string; type: string }

A normalized resource object

isArray

isArray(value: any): value is any[]

- Defined in src/util.ts:6
Determines if a reference is an Array

Parameters
- value: any
  
  Reference to check
Returns value is any[]

isDefined

isDefined(value: any): boolean

- Defined in src/util.ts:15
Determines if a reference is defined

Parameters
- value: any
  
  Reference to check
Returns boolean

isObject

isObject(value: any): value is object

- Defined in src/util.ts:24
Determines if a reference is an 'Object'

Parameters
- value: any
  
  Reference to check
Returns value is object

isPlainObject

isPlainObject(value: any): value is object

- Defined in src/util.ts:36
Determines if a reference is a plain Object. A "plain" object is typically created by {} or new Object(). Some types such as arrays and null, while technically objects, are not considered plain objects.

Parameters
- value: any
  
  Reference to check
Returns value is object

linkRelationships

linkRelationships(relationships: NormalizedRelationships, included: ResourceObject[]): NormalizedRelationships

- Defined in src/normalize.ts:60
Merges included relationship data with resource object relationships

Parameters
- relationships: NormalizedRelationships
  
  A normalized object of relationship resources
- included: ResourceObject[]
  
  The included relationship resources
Returns NormalizedRelationships

A merged relationship object

mapResources

mapResources(data: NormalizedResourceOrResources): NormalizedResource[]

- Defined in src/mapResources.ts:9
Returns a collection of resources with only ID & Type properties

Parameters
- data: NormalizedResourceOrResources
  
  A normalized resource object or collection of resource objects
Returns NormalizedResource[]

normalizeCollection

normalizeCollection(resources: ResourceObject[], included?: ResourceObject[]): NormalizedResource[]

- Defined in src/normalize.ts:111
Normalizes a collection of resource objects

Parameters
- resources: ResourceObject[]
  
  The collection of resources
- Default value included: ResourceObject[] = []
  
  Included relationship resources
Returns NormalizedResource[]

A collection of normalized resource objects

normalizeResource

normalizeResource(resource: ResourceObject, included?: ResourceObject[]): { id: string; type: string } | { id: string; type: string } | { id: string; type: string } | { id: string; type: string }

- Defined in src/normalize.ts:90
Normalizes a resource by hoisting the attributes and linking relationships

Parameters
- resource: ResourceObject
  
  A resource object
- Default value included: ResourceObject[] = []
  
  Included relationship resources
Returns { id: string; type: string } | { id: string; type: string } | { id: string; type: string } | { id: string; type: string }

A normalized resource object

parseDate

parseDate(value: string): string | number

- Defined in src/util.ts:49
Converts a date string into Unix Epoch time

Parameters
- value: string
  
  A date string
Returns string | number

The time in milliseconds or the original value if it fails to parse

serialize

serialize(obj: NormalizedResource, options?: SerializeOptions): Request

- Defined in src/serialize.ts:22
Serializes an object into a JSON API structure

Parameters
- obj: NormalizedResource
  
  A normalized resource object
- Default value options: SerializeOptions = {}
  
  Serialization options
Returns Request

A JSON API compliant resource object

serializeMutation

serializeMutation(op: OperationType, path: string, resources: NormalizedResource[]): { op: OperationType; path: string; value: ResourceObject }[]

- Defined in src/serializeMutation.ts:13
Serializes normalized resources into a JSON API-PATCH structure

Ref: https://goo.gl/bB58Wg

Parameters
- op: OperationType
  
  Operation to perform
- path: string
  
  Resource path relative to the root URL
- resources: NormalizedResource[]
  
  Resources to serialize
Returns { op: OperationType; path: string; value: ResourceObject }[]

serializeObject

serializeObject(obj: Attributes, param?: undefined | string): string

- Defined in src/serializeParams.ts:17
Recursively stringifies nested objects

Parameters
- obj: Attributes
  
  An object
- Optional param: undefined | string
  
  The current query parameter
Returns string

A URI component

serializeParams

serializeParams(params?: Params, options?: SerializeParamsOptions): string

- Defined in src/serializeParams.ts:67
Serializes a parameter object into a URL query string

Parameters
- Default value params: Params = {}
  
  Query parameters
- Default value options: SerializeParamsOptions = {}
  
  Serialization options
Returns string

A URL query string

toQueryString

toQueryString(params: ParamsObject, prefix?: boolean): string

- Defined in src/serializeParams.ts:42
Constructs a URL query string for JSON API parameters

Parameters
- params: ParamsObject
  
  Parameters to parse
- Default value prefix: boolean = false
  
  Prefix returned string with ? (default false)
Returns string

A URL query string

validateRelationship

validateRelationship(obj: RelationshipRef): void

- Defined in src/validation.ts:33
Throws if the provided relationship object doesn't have expected properties

Parameters
- obj: RelationshipRef
Returns void

validateResource

validateResource(obj: NormalizedResource, idRequired?: undefined | false | true): void

- Defined in src/validation.ts:15
Throws if the provided resource doesn't have expected properties

Parameters
- obj: NormalizedResource
- Optional idRequired: undefined | false | true
Returns void

Generated using TypeDoc

Elide JSON API Client

Features

Basic Usage

Documentation

API Docs

Wiki

Credits

Contributors ✨

License

Index

Classes

Interfaces

Type aliases

Variables

Functions

Type aliases

Attribute

ElideError

Type declaration

error: string

message: string

path: string

status: number

timestamp: string

NewResourceObject

Type declaration

Optional attributes?: Attributes

Optional id?: undefined | string

Optional links?: Links

Optional relationships?: Relationships

type: string

NormalizedResourceOrResources

Operation

Type declaration

op: OperationType

path: string

value: ResourceObject

OperationType

Operations

PageParams

Type declaration

Optional limit?: undefined | number

Optional number?: undefined | number

Optional offset?: undefined | number

Optional size?: undefined | number

Optional totals?: undefined | false | true

Params

Type declaration

Optional fields?: string | Attributes

Optional filter?: string | Attributes

Optional include?: string | string[]

Optional page?: undefined | number

Optional pageSize?: undefined | number

Optional sort?: string | string[]

RelationshipRef

Type declaration

id: string

type: string

ResourceObject

Type declaration

Optional attributes?: Attributes

id: string

Optional links?: Links

Optional relationships?: Relationships

type: string

ResourceObjectOrObjects

ResourceObjects

SerializeOptions

Type declaration

Optional dateAttrs?: string[]

Optional idRequired?: undefined | false | true

Optional protectedAttrs?: string[]

SerializeParamsOptions

Type declaration

Optional prefix?: undefined | false | true

Optional size?: undefined | number

Optional totals?: undefined | false | true

Optional type?: undefined | string

Variables

Const ID_REQUIRED