diff --git a/packages/request-utils/README.md b/packages/request-utils/README.md index b44009e3ee5..8437c6260b1 100644 --- a/packages/request-utils/README.md +++ b/packages/request-utils/README.md @@ -1,13 +1,66 @@ -@ember-data/tracking -============================================================================ - -Tracking Primitives for controlling change notification of Tracked properties when working with EmberData - -> Note: This is a V2 Addon, but we have intentionally configured it to act and report as a V1 Addon due -to bugs with ember-auto-import. -> -> We can remove the V1 tag if ember-auto-import will no longer attempt -to load V2 addons or if it is fixed to work with V1 addons with custom addon trees and also dedupes modules for test apps. -> -> You can still consume this as a normal library. -> In other projects. +

+ + +

+ +

Utilities for Requests

+ +This package provides Simple utility function to assist in url building, query params, and other common request operations. + +It's built for [*Ember***Data**](https://github.com/emberjs/data/) but useful more broadly if you're looking for lightweight functions to assist in working with urls and query params. + +## Installation + +Install using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/) + +```no-highlight +pnpm add @ember-data/request-utils +``` +## Utils + +- [buildBaseUrl]() +- [sortQueryParams]() +- [buildQueryParams]() +- [filterEmpty]() + +### As a Library Primitive + +These primitives may be used directly or composed by request builders to provide a consistent interface for building requests. + +For instance: + +```ts +import { buildBaseURL, buildQueryParams } from '@ember-data/request-utils'; + +const baseURL = buildBaseURL({ + host: 'https://api.example.com', + namespace: 'api/v1', + resourcePath: 'emberDevelopers', + op: 'query', + identifier: { type: 'ember-developer' } +}); +const url = `${baseURL}?${buildQueryParams({ name: 'Chris', include:['pets'] })}`; +// => 'https://api.example.com/api/v1/emberDevelopers?include=pets&name=Chris' +``` + +This is useful, but not as useful as the REST request builder for query which is sugar over this (and more!): + +```ts +import { query } from '@ember-data/rest/request'; + +const options = query('ember-developer', { name: 'Chris', include:['pets'] }); +// => { url: 'https://api.example.com/api/v1/emberDevelopers?include=pets&name=Chris' } +// Note: options will also include other request options like headers, method, etc. +``` diff --git a/packages/request-utils/ember-data-logo-dark.svg b/packages/request-utils/ember-data-logo-dark.svg new file mode 100644 index 00000000000..737a4aa4321 --- /dev/null +++ b/packages/request-utils/ember-data-logo-dark.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/packages/request-utils/ember-data-logo-light.svg b/packages/request-utils/ember-data-logo-light.svg new file mode 100644 index 00000000000..58ac3d4e544 --- /dev/null +++ b/packages/request-utils/ember-data-logo-light.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/packages/rest/src/-private/builders/find-record.ts b/packages/rest/src/-private/builders/find-record.ts index 85ec6883120..43161647fff 100644 --- a/packages/rest/src/-private/builders/find-record.ts +++ b/packages/rest/src/-private/builders/find-record.ts @@ -27,7 +27,25 @@ type FindRecordOptions = ConstrainedRequestOptions & { * ```ts * import { findRecord } from '@ember-data/rest/request'; * - * const data = await store.request(findRecord({ type: 'person', id: '1' })); + * const data = await store.request(findRecord('person', '1')); + * ``` + * + * **With Options** + * + * ```ts + * import { findRecord } from '@ember-data/rest/request'; + * + * const options = findRecord('person', '1', { include: ['pets', 'friends'] }); + * const data = await store.request(options); + * ``` + * + * **With an Identifier** + * + * ```ts + * import { findRecord } from '@ember-data/rest/request'; + * + * const options = findRecord({ type: 'person', id: '1' }, { include: ['pets', 'friends'] }); + * const data = await store.request(options); * ``` * * @method findRecord diff --git a/packages/rest/src/request.ts b/packages/rest/src/request.ts index 221155e276b..9d1d63258d5 100644 --- a/packages/rest/src/request.ts +++ b/packages/rest/src/request.ts @@ -1,9 +1,65 @@ /** - * Request Builders ready to go for use with `store.request()` - * and most conventional REST APIs. - * - * Resource types are pluralized and camelized for the url. - * + *

+ +

+ +This package provides utilities for working with **REST**ful APIs with [*Ember***Data**](https://github.com/emberjs/data/). + +## Installation + +Install using your javascript package manager of choice. For instance with [pnpm](https://pnpm.io/) + +```no-highlight +pnpm add @ember-data/json-api +``` + +## Usage + +Request builders are functions that produce [Fetch Options](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). +They take a few contextual inputs about the request you want to make, abstracting away the gnarlier details. + +For instance, to fetch a resource from your API + +```ts +import { findRecord } from '@ember-data/rest/request'; + +const options = findRecord('ember-developer', '1', { include: ['pets', 'friends'] }); + +/* + => { + url: 'https://api.example.com/v1/emberDevelopers/1?include=friends,pets', + method: 'GET', + headers: , // 'Content-Type': 'application/json; charset=utf-8' + op: 'findRecord'; + records: [{ type: 'ember-developer', id: '1' }] + } +* / +``` + +Request builder output is ready to go for use with [store.request](https://api.emberjs.com/ember-data/release/classes/Store/methods/request?anchor=request), +[manager.request](https://api.emberjs.com/ember-data/release/classes/RequestManager/methods/request?anchor=request) and most conventional REST APIs. + +Resource types are pluralized and camelized for the url. + +URLs are stable. The same query will produce the same URL every time, even if the order of keys in +the query or values in an array changes. + +URLs follow the most common REST format (camelCase pluralized resource types). + +### Available Builders + +- [createRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/createRecord) +- [deleteRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/deleteRecord) +- [findRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/findRecord) +- [query](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/query) +- [updateRecord](https://api.emberjs.com/ember-data/release/functions/@ember-data%2Frest/updateRecord) + * @module @ember-data/rest/request * @main @ember-data/rest/request * @public