{"id":22800004,"url":"https://github.com/dadi/api-wrapper","last_synced_at":"2025-06-23T19:06:51.286Z","repository":{"id":6349775,"uuid":"55319117","full_name":"dadi/api-wrapper","owner":"dadi","description":"A high-level library for interacting with DADI API","archived":false,"fork":false,"pushed_at":"2024-10-03T13:18:12.000Z","size":227,"stargazers_count":7,"open_issues_count":12,"forks_count":3,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-05-29T02:16:53.540Z","etag":null,"topics":["api-client","api-gateway","api-wrapper","dadi","dadi-api"],"latest_commit_sha":null,"homepage":"https://docs.dadi.cloud/api-wrapper","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dadi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-02T22:27:09.000Z","updated_at":"2024-10-03T13:18:16.000Z","dependencies_parsed_at":"2023-01-13T13:57:12.627Z","dependency_job_id":null,"html_url":"https://github.com/dadi/api-wrapper","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/dadi/api-wrapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapi-wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapi-wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapi-wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapi-wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dadi","download_url":"https://codeload.github.com/dadi/api-wrapper/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapi-wrapper/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261539318,"owners_count":23174136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","api-gateway","api-wrapper","dadi","dadi-api"],"created_at":"2024-12-12T07:10:46.675Z","updated_at":"2025-06-23T19:06:51.204Z","avatar_url":"https://github.com/dadi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DADI API wrapper\n\n\u003e A high-level library for interacting with DADI API\n\n[![npm (scoped)](https://img.shields.io/npm/v/@dadi/api-wrapper.svg?maxAge=10800\u0026style=flat-square)](https://www.npmjs.com/package/@dadi/api-wrapper)\n[![Coverage Status](https://coveralls.io/repos/github/dadi/api-wrapper/badge.svg?branch=master)](https://coveralls.io/github/dadi/api-wrapper?branch=master)\n[![Build Status](https://travis-ci.org/dadi/api-wrapper.svg?branch=master)](https://travis-ci.org/dadi/api-wrapper)\n[![JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](http://standardjs.com/)\n\n## Overview\n\n[DADI API](https://github.com/dadi/api) is a high performance RESTful API layer designed in support of API-first development and the principle of COPE.\n\nThis library provides a high-level abstraction of the REST architecture style, exposing a set of chainable methods that allow developers to compose complex read and write operations using a simplistic and natural syntax.\n\n## Getting started\n\n1. Install the `@dadi/api-wrapper` module:\n\n   ```shell\n   npm install @dadi/api-wrapper --save\n   ```\n\n2. Add the library and configure the API settings:\n\n   ```js\n   const DadiAPI = require('@dadi/api-wrapper')\n   const api = new DadiAPI({\n     uri: 'http://api.example.com',\n     port: 80,\n     credentials: {\n       clientId: 'johndoe',\n       secret: 'f00b4r'\n     },\n     property: 'test'\n   })\n   ```\n\n3. Make a query:\n\n   ```js\n   // Example: getting all documents where `name` contains \"john\" and age is greater than 18\n   api\n     .in('users')\n     .whereFieldContains('name', 'john')\n     .whereFieldIsGreaterThan('age', 18)\n     .find()\n     .then(response =\u003e {\n       // Use documents here\n     })\n   ```\n\n## Methods\n\nEach query consists of a series of chained methods to form the request, always containing a terminator method. Terminators return a Promise with the result of one or more requests to the database and can make use of a series of [filtering methods](#filters) to create the desired subset of documents to operate on.\n\n### Terminators\n\n#### `.apply(callback)`\n\nUpdates a list of documents with the result of individually applying `callback` to them.\n\n```js\napi\n  .in('users')\n  .whereFieldExists('gender')\n  .apply(document =\u003e {\n    document.name =\n      document.gender === 'male'\n        ? `Mr ${document.name}`\n        : `Mrs ${document.name}`\n\n    return document\n  })\n```\n\n#### `.create()`\n\nCreates a document.\n\n```js\n// Example\napi\n  .in('users')\n  .create({\n    name: 'John Doe',\n    age: 45,\n    address: '123 Fake St'\n  })\n  .then(function(doc) {\n    console.log('New document:', doc)\n  })\n  .catch(function(err) {\n    console.log('! Error:', err)\n  })\n```\n\n#### `.delete()`\n\nDeletes one or more documents.\n\n```js\napi\n  .in('users')\n  .whereFieldDoesNotExist('name')\n  .delete()\n```\n\n#### `.find(options)`\n\nReturns a list of documents.\n\n```js\napi\n  .in('users')\n  .whereFieldIsGreaterThan('age', 21)\n  .useFields(['name', 'age'])\n  .find(options)\n```\n\n`options` is one of the following:\n\n- `extractResults` (Boolean): Selects whether just the results array should be returned, rather than the entire API response.\n- `extractMetadata` (Boolean): Selects whether just the metadata object should be returned, rather than the entire API response.\n\n#### `.getCollections()`\n\nGets the list of collections for the API.\n\n```js\napi.getCollections()\n```\n\n#### `.getConfig()`\n\nGets the config for a collection or for the API.\n\n```js\n// Gets the collection config\napi.in('users').getConfig()\n```\n\n```js\n// Gets the API config\napi.getConfig()\n```\n\n#### `.getLanguages()`\n\nGets the list of languages supported by the API.\n\n```js\napi.getLanguages().then(({metadata, results}) =\u003e {\n  /*\n    {\n      \"defaultLanguage\": {\n        \"code\": \"en\",\n        \"name\": \"English\",\n        \"local\": \"English\"\n      },\n      \"totalCount\": 2\n    }  \n  */\n  console.log(metadata)\n\n  /*\n    [\n      {\n        \"code\": \"en\",\n        \"name\": \"English\",\n        \"local\": \"English\",\n        \"default\": true\n      },\n      {\n        \"code\": \"pt\",\n        \"name\": \"Portuguese\",\n        \"local\": \"Português\"\n      }\n    ]\n  */\n  console.log(results)\n})\n```\n\n#### `.getSignedUrl()`\n\nGets a signed URL from a media collection.\n\n```js\napi.in('images').getSignedUrl({\n  fileName: 'foobar.jpg'\n})\n```\n\n#### `.getStats()`\n\nGets collection stats.\n\n```js\napi.in('users').getStats()\n```\n\n#### `.getStatus()`\n\nGets the the API status.\n\n```js\napi.getStatus()\n```\n\n#### `.update(update)`\n\nUpdates a list of documents.\n\n```js\napi\n  .in('users')\n  .whereFieldIsLessThan('age', 18)\n  .update({\n    adult: false\n  })\n```\n\n### Filters\n\nFiltering methods are used to create a subset of documents that will be affected by subsequent operation terminators.\n\n#### `.goToPage(page)`\n\nDefines the page of documents to be used.\n\n```js\n// Example\napi.goToPage(3)\n```\n\n#### `.limitTo(limit)`\n\nDefines a maximum number of documents to be retrieved.\n\n```js\n// Example\napi.limitTo(10)\n```\n\n#### `.requireFeature(featureCode)`\n\nQueries the API for support of a given feature and throws a `MISSING_FEATURES` error if it's not supported.\n\n```js\n// Example\napi.requestFeature('aclv1')\n```\n\n#### `.setSearchQuery(query)`\n\nSets the query to use for a collection search.\n\n```js\n// Example\napi\n  .in('users')\n  .setSearchQuery('John')\n  .find()\n```\n\n#### `.sortBy(field, order)`\n\nSelects a field to sort on and the sort direction. Order defaults to ascending (`asc`).\n\n```js\n// Example\napi.sortBy('age', 'desc')\n```\n\n#### `.useFields(fields)`\n\nSelects the fields to be returned in the response. Accepts array format.\n\n```js\n// Example\napi.useFields(['name', 'age'])\n```\n\n#### `.useLanguage(language)`\n\nSets the language to be used when querying. Accepts an ISO 639 language code in string format.\n\n```js\n// Example\napi.useLanguage('en')\n```\n\n#### `.where(query)`\n\nFilters documents using a MongoDB query object or a Aggregation Pipeline array. The methods above are ultimately just syntatic sugar for `where()`. This method can be used for complex queries that require operations not implemented by any other method.\n\n```js\n// Example\napi.where({name: 'John Doe'})\n```\n\n#### `.whereClientIs(value)`\n\nApplicable when in \"client mode\". Selects the client with ID equal to `value`.\n\n```js\n// Example\napi.inClients().whereClientIs('testClient')\n```\n\n#### `.whereClientIsSelf()`\n\nApplicable when in \"client mode\". Selects the client associated with the bearer token being used.\n\n```js\n// Example\napi.inClients().whereClientIsSelf()\n```\n\n#### `.whereFieldBeginsWith(field, text)`\n\nFilters documents where `field` begins with `text`.\n\n```js\n// Example\napi.whereFieldBeginsWith('name', 'john')\n```\n\n#### `.whereFieldContains(field, text)`\n\nFilters documents where `field` contains `text`.\n\n```js\n// Example\napi.whereFieldContains('name', 'john')\n```\n\n#### `.whereFieldDoesNotContain(field, text)`\n\nFilters documents `field` does not contain `text`.\n\n```js\n// Example\napi.whereFieldDoesNotContain('name', 'john')\n```\n\n#### `.whereFieldEndsWith(field, text)`\n\nFilters documents where field starts with `text`.\n\n```js\n// Example\napi.whereFieldEndsWith('name', 'john')\n```\n\n#### `.whereFieldExists(field)`\n\nFilters documents that contain a field.\n\n```js\n// Example\napi.whereFieldExists('name')\n```\n\n#### `.whereFieldDoesNotExist(field)`\n\nFilters documents that do not contain a field.\n\n```js\n// Example\napi.whereFieldDoesNotExist('address')\n```\n\n#### `.whereFieldIsEqualTo(field, value)`\n\nFilters documents where `field` is equal to `value`.\n\n```js\n// Example\napi.whereFieldIsEqualTo('age', 53)\n```\n\n#### `.whereFieldIsGreaterThan(field, value)`\n\nFilters documents where `field` is greater than `value`.\n\n```js\n// Example\napi.whereFieldIsGreaterThan('age', 18)\n```\n\n#### `.whereFieldIsGreaterThanOrEqualTo(field, value)`\n\nFilters documents where `field` is greater than or equal to `value`.\n\n```js\n// Example\napi.whereFieldIsGreaterThanOrEqualTo('age', 19)\n```\n\n#### `.whereFieldIsLessThan(field, value)`\n\nFilters documents where `field` is less than `value`.\n\n```js\n// Example\napi.whereFieldIsLessThan('age', 65)\n```\n\n#### `.whereFieldIsLessThanOrEqualTo(field, value)`\n\nFilters documents where `field` is less than or equal to `value`.\n\n```js\n// Example\napi.whereFieldIsLessThanOrEqualTo('age', 64)\n```\n\n#### `.whereFieldIsOneOf(field, matches)`\n\nFilters documents where the value of `field` is one of the elements of `matches`.\n\n```js\n// Example\napi.whereFieldIsOneOf('name', ['John', 'Jack', 'Peter'])\n```\n\n#### `.whereFieldIsNotEqualTo(field, value)`\n\nFilters documents where `field` is not equal to `value`.\n\n```js\n// Example\napi.whereFieldIsEqualTo('age', 53)\n```\n\n#### `.whereFieldIsNotOneOf(field, matches)`\n\nFilters documents where the value of `field` is not one of the elements of `matches`.\n\n```js\n// Example\napi.whereFieldIsNotOneOf('name', ['Mark', 'Nathan', 'David'])\n```\n\n#### `.whereHookNameIs(name)`\n\nSelects the hook with a given name.\n\n```js\n// Example\napi.whereFieldIsNotOneOf('name', ['Mark', 'Nathan', 'David'])\n```\n\n#### `.withComposition(value)`\n\nDefines whether nested documents should be resolved using composition. The default is to let API decide based on the queried collection's settings.\n\n```js\n// Example\napi.withComposition()\napi.withComposition(true) // same as above\napi.withComposition(false)\n```\n\n### Other methods\n\n#### `.fromEndpoint(endpoint)`\n\nSelects a custom endpoint to use. Please note that unlike collections, custom endpoints do not have a standardised syntax, so it is up to the authors to make sure the endpoint complies with standard DADI API formats, or they will not function as expected.\n\n```js\n// Example\napi.fromEndpoint('custom-endpoint')\n```\n\n#### `.in(collection)`\n\nSelects the collection to use.\n\n```js\n// Example\napi.in('users')\n```\n\n#### `.inClients()`\n\nSelects \"client mode\", meaning filters and terminators will operate on clients and not on documents.\n\n```js\n// Example\napi.inClients()\n```\n\n#### `.inHooks()`\n\nSelects \"hook mode\", meaning filters and terminators will operate on hooks and not on documents.\n\n```js\n// Example\napi.inMedia('images')\n```\n\n#### `.inMedia(bucket)`\n\nSelects a media bucket to be used.\n\n```js\n// Example\napi.inMedia('images')\n```\n\n#### `.inProperty(property)`\n\nSelects the property to use. Overrides any property defined in the initialisation options, and is reset when called without arguments.\n\n```js\n// Example\napi.inProperty('test')\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadi%2Fapi-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdadi%2Fapi-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadi%2Fapi-wrapper/lists"}