APIRequester

MMO.core · 2 symbols · generated 5 Oct 2026

class

APIRequester

Wrapper to query any API implementing JSON API

class MMO.core.APIRequester

Namespace: MMO.core

# Supported query - pagination : ?page[offset]=0&page[limit]=10 - sorting : ?sort=-created,title - fields : ?fields=title,-body,people/name - filters : ?filters[age][$>]=20&filters[age][$<]=50&filters[author/status]=active - list only id : ?onlydIds

Index

	collection readonly accessor	The collection name, read back out of the url through the `repository` path pattern.
	repository readonly accessor	The repository name, read back out of the url through the `repository` path pattern.
	offset accessor	Get the starting offset of the data
	limit accessor	Get the maximum number of data to return
	sort accessor	Get a list of the fields used to sort the data the value associated to the field is a boolean that indicates if the sorting is ascending (false for descending)
	fields accessor	Get a list of the fields to show the value associated to the field is a boolean that indicates if the field is shown (true) or hidden (false)
	filters accessor	The query filters, as a plain object.
	search accessor	The full text search parameters, as a plain object.
	searchType accessor
	dataCount readonly accessor
	dataClass readonly accessor	The php class name of the entities the last response carried.
	pageOffset readonly accessor	The index of the first entity of the last response, within the whole collection.
	pageIndex readonly accessor	The page number of the last response.
	pageCount readonly accessor	How many pages the query spans.
	previousPageUrl readonly accessor
	nextPageUrl readonly accessor
	firstPageUrl readonly accessor
	lastPageUrl readonly accessor
	constructor(url)
	setUrl(url, keepSearch)	Point the requester at another url, rebuilding its search parameters.
	setUrlSearch(search)	Replace the whole query string.
	Collection(collection, repository) static	Get an instance meant to interact with the framework repository controller
	List(collection, filters, repository) static	A requester set up to return identifiers only: ideal to populate a picker.
	setLimitDate(dateStart, dateEnd, dateField)	Restrict the query to a date window, replacing any window already set on that field.
	getLimitDate(dateField)	Read back the window set by `MMO.core.APIRequester#setLimitDate`
	splitFieldsList(key)	Split a string representing a list of fields
	joinFieldsList(key, value)	Join a value to create a list of fields as a string
	indexOfFieldsList(key, field, value)	Get/set the index of field (even if the field is prefixed with '-')
	indexAtFieldsList(key, index)
	addFieldsList(key, field, value, order)	Add a field to the field list
	removeFieldsList(key, field)	Remove a field from the field list
	getSortParam()
	isSortOnlyId()
	clearSort()	Drop the sorting, letting the server apply its own order.
	isEmptySort()
	addSort(field, asc, order)	Add a field to the sort, or move one already there.
	removeSort(field)
	indexOfSort(field, value)	Read, or change, a sort field's position.
	indexAtSort(index)
	listOnly(value)	Only return a list of identifier
	clearFields()	Drop the field selection, asking the server for everything it exposes.
	getFieldsParam()
	addField(field, visible, order)	Add a field to the selection, or move one already there.
	removeField(field)
	indexOfField(field, value)	Read, or change, a field's position.
	indexAtField(index)
	setSearchValue(key, value)	Set one search parameter, leaving the others alone.
	fetch(data, opts, method)	Run the query, aborting any request this requester still had in flight.
	fetchXLSX(fields, opts)	Download the current query as a spreadsheet, by swapping the url's extension.
	fetchCSV(fields, opts)	Download the current query as a csv file.
	fetchJSON(fields, opts)	Download the current query as a json file.
	abort()	Abort fetch
	get(ids)	Get entities
	update(data, opts)	Update entities (MUST have ids)
	insert(data, opts)	Insert entities (NO ids)
	remove(data, opts)	Delete entities (MUST have ids)
	patch(data, opts)	Send a patch request that allows setting the status of an entity
	setPreviousUrl()	Set api's url to the previous page NOTE: this only change the url.
	setNextUrl()	Set api's url to the next page NOTE: this only change the url.

Properties18

collection

readonlyaccessorAPIRequester.js:48

The collection name, read back out of the url through the repository path pattern.

get collection()

Type: ?string

repository

readonlyaccessorAPIRequester.js:56

The repository name, read back out of the url through the repository path pattern.

get repository()

Type: ?string

offset

accessorAPIRequester.js:92

Get the starting offset of the data

get offset() set offset(value)

limit

accessorAPIRequester.js:108

Get the maximum number of data to return

get limit() set limit(value)

sort

accessorAPIRequester.js:300

Get a list of the fields used to sort the data the value associated to the field is a boolean that indicates if the sorting is ascending (false for descending)

get sort() set sort(value)

fields

accessorAPIRequester.js:405

Get a list of the fields to show the value associated to the field is a boolean that indicates if the field is shown (true) or hidden (false)

get fields() set fields(value)

filters

accessorAPIRequester.js:469

The query filters, as a plain object. Operators are nested: {age: {'$gte': 20}}.

get filters() set filters(value)

Type: Object

search

accessorAPIRequester.js:493

The full text search parameters, as a plain object.

get search() set search(value)

Type: Object

searchType

accessorAPIRequester.js:518

get searchType() set searchType(value)

Type: ?string

dataCount

readonlyaccessorAPIRequester.js:690

get dataCount()

dataClass

readonlyaccessorAPIRequester.js:698

The php class name of the entities the last response carried.

get dataClass()

Type: ?string

pageOffset

readonlyaccessorAPIRequester.js:706

The index of the first entity of the last response, within the whole collection.

get pageOffset()

Type: ?number

pageIndex

readonlyaccessorAPIRequester.js:714

The page number of the last response.

get pageIndex()

Type: ?number

pageCount

readonlyaccessorAPIRequester.js:722

How many pages the query spans.

get pageCount()

Type: ?number

previousPageUrl

readonlyaccessorAPIRequester.js:729

get previousPageUrl()

Type: ?string

nextPageUrl

readonlyaccessorAPIRequester.js:750

get nextPageUrl()

Type: ?string

firstPageUrl

readonlyaccessorAPIRequester.js:771

get firstPageUrl()

Type: ?string

lastPageUrl

readonlyaccessorAPIRequester.js:778

get lastPageUrl()

Type: ?string

Methods41

constructor(url)

APIRequester.js:15

constructor(url = '')

url = ''

setUrl(url, keepSearch)

APIRequester.js:28

Point the requester at another url, rebuilding its search parameters.

setUrl(url, keepSearch = false)

ALWAYS go through this rather than assigning `url`, or `searchParams` goes stale.

url	`string` \| `URL`	resolved against the site url when relative
keepSearch = false	`boolean`	carry the current query over to the new url

setUrlSearch(search)

APIRequester.js:39

Replace the whole query string.

setUrlSearch(search)

search string with or without its leading '?'

Collection(collection, repository)

staticAPIRequester.js:67

Get an instance meant to interact with the framework repository controller

static Collection(collection, repository = null)

collection
repository = null
returns	MMO.core.APIRequester

List(collection, filters, repository)

staticAPIRequester.js:78

A requester set up to return identifiers only: ideal to populate a picker.

static List(collection, filters, repository = null)

collection	`string`
filters	`Object`
repository = null	`?string`	defaults to 'main'
returns	MMO.core.APIRequester

setLimitDate(dateStart, dateEnd, dateField)

APIRequester.js:128

Restrict the query to a date window, replacing any window already set on that field.

setLimitDate(dateStart, dateEnd, dateField = 'ctime')

Drops the pagination limit, since the window is what bounds the result.

dateStart	`Date` \| `string`
dateEnd	`Date` \| `string`
dateField = 'ctime'	`string`	the entity property carrying the date

getLimitDate(dateField)

APIRequester.js:153

Read back the window set by MMO.core.APIRequester#setLimitDate

getLimitDate(dateField = 'ctime')

dateField = 'ctime'	`string`
returns	`?[?string, ?string]`	null when no window is set

splitFieldsList(key)

APIRequester.js:179

Split a string representing a list of fields

splitFieldsList(key)

key	`string`	the key in the searchParams
returns	`field: boolean`	}

joinFieldsList(key, value)

APIRequester.js:198

Join a value to create a list of fields as a string

joinFieldsList(key, value)

key	`string`	the key in the searchParams
value	`string` \| `Array` \| `Object`	- a string: list of field's name separated by comma. use `-` as a field prefix to set value to false. - an array: list of field's name - an object: {field}: {boolean}
returns	`string`

indexOfFieldsList(key, field, value)

APIRequester.js:215

Get/set the index of field (even if the field is prefixed with '-')

indexOfFieldsList(key, field, value = null)

key	`string`	the key in the searchParams
field	`string`	the field's name (can be prefixed with '-')
value = null	`int` \| `null`	if not null, move the field to this index
returns	`number`	-1 if the field was not found

indexAtFieldsList(key, index)

APIRequester.js:239

indexAtFieldsList(key, index)

key	`string`	the key in the searchParams
index	`number`
returns	`?string`	the field at that position, with its prefix; null when out of range

addFieldsList(key, field, value, order)

APIRequester.js:252

Add a field to the field list

addFieldsList(key, field, value = null, order = null)

key	`string`	the key in the searchParams
field	`string`	the field's name (can be prefixed with '-')
value = null	`boolean` \| `null`	if null, will use the field as it is (with/without its prefix), else force the prefix on the field
order = null
returns	`number`	-1 if the field was not found

removeFieldsList(key, field)

APIRequester.js:283

Remove a field from the field list

removeFieldsList(key, field)

key	`string`	the key in the searchParams
field	`string`	the field's name (can be prefixed with '-')
returns	`boolean`	true if field was removed

getSortParam()

APIRequester.js:315

getSortParam()

returns string the raw sort parameter, '' when unset

isSortOnlyId()

APIRequester.js:322

isSortOnlyId()

returns boolean true when the result is sorted by id and nothing else

clearSort()

APIRequester.js:330

Drop the sorting, letting the server apply its own order.

clearSort()

isEmptySort()

APIRequester.js:337

isEmptySort()

returns boolean true when sorting is explicitly set to nothing (NOT the same as unset)

addSort(field, asc, order)

APIRequester.js:348

Add a field to the sort, or move one already there.

addSort(field, asc = null, order = null)

field	`string`	prefix with '-' for a descending sort
asc = null	`?boolean`	force the direction, ignoring the field's own prefix
order = null	`?number`	the position among the sort fields; appended when null
returns	`number`	the field's position

removeSort(field)

APIRequester.js:356

removeSort(field)

field	`string`	with or without its prefix
returns	`boolean`	false when the field was not part of the sort

indexOfSort(field, value)

APIRequester.js:366

Read, or change, a sort field's position.

indexOfSort(field, value = null)

field	`string`	with or without its prefix
value = null	`?number`	move the field to this position
returns	`number`	the position, -1 when the field is not part of the sort

indexAtSort(index)

APIRequester.js:374

indexAtSort(index)

index	`number`
returns	`?string`	the sort field at that position

listOnly(value)

APIRequester.js:385

Only return a list of identifier

listOnly(value = true)

value = true

clearFields()

APIRequester.js:396

Drop the field selection, asking the server for everything it exposes.

clearFields()

getFieldsParam()

APIRequester.js:419

getFieldsParam()

returns string the raw fields parameter, '' when unset

addField(field, visible, order)

APIRequester.js:430

Add a field to the selection, or move one already there.

addField(field, visible = null, order = null)

field	`string`	prefix with '-' to hide it
visible = null	`?boolean`	force the visibility, ignoring the field's own prefix
order = null	`?number`	the position among the fields; appended when null
returns	`number`	the field's position

removeField(field)

APIRequester.js:438

removeField(field)

field	`string`	with or without its prefix
returns	`boolean`	false when the field was not part of the selection

indexOfField(field, value)

APIRequester.js:448

Read, or change, a field's position.

indexOfField(field, value = null)

field	`string`	with or without its prefix
value = null	`?number`	move the field to this position
returns	`number`	the position, -1 when the field is not selected

indexAtField(index)

APIRequester.js:456

indexAtField(index)

index	`number`
returns	`?string`	the field at that position

setSearchValue(key, value)

APIRequester.js:510

Set one search parameter, leaving the others alone.

setSearchValue(key, value)

key	`string`
value	`*`	null or undefined drops it

fetch(data, opts, method)

APIRequester.js:541

Run the query, aborting any request this requester still had in flight.

fetch(data = null, opts = {}, method = null)

The response is kept in `this.response` for the pagination getters.

data = null	`?(Object` \| `Array)`	a body; a GET carries it in the query string instead
opts = {}	`Object`	options for the Request
method = null	`?string`	defaults to GET without data, POST with
returns	`Promise<Object>`	the entities, indexed by uid

fetchXLSX(fields, opts)

APIRequester.js:581

Download the current query as a spreadsheet, by swapping the url's extension.

fetchXLSX(fields = null, opts = {})

fields = null	`?Array<string>`	export these fields instead of the selected ones
opts = {}	`Object`	options for the Request
returns	`Promise<Blob>`

fetchCSV(fields, opts)

APIRequester.js:595

Download the current query as a csv file.

fetchCSV(fields = null, opts = {})

fields = null	`?Array<string>`	export these fields instead of the selected ones
opts = {}	`Object`	options for the Request
returns	`Promise<Blob>`

fetchJSON(fields, opts)

APIRequester.js:610

Download the current query as a json file.

fetchJSON(fields = null, opts = {})

NOTE: this DOWNLOADS the result; `MMO.core.APIRequester#fetch` to consume it in code.

fields = null	`?Array<string>`	export these fields instead of the selected ones
opts = {}	`Object`	options for the Request
returns	`Promise<Blob>`

abort()

APIRequester.js:621

Abort fetch

abort()

get(ids)

APIRequester.js:635

Get entities

get(ids = null)

ids = null	`array` \| `string` \| `int` \| `null`	the ids to look for. if null, load everything
returns	`Promise<*>`

update(data, opts)

APIRequester.js:653

Update entities (MUST have ids)

update(data, opts = {})

data	MMO.elements.Entity \| `object` \| `Array`	to send (can be multiple entities or just one)
opts = {}	`object`	the options to pass to the request (see documentation of javascript `Request`)
returns	`Promise<*>`

insert(data, opts)

APIRequester.js:663

Insert entities (NO ids)

insert(data, opts = {})

data	MMO.elements.Entity \| `object` \| `Array`	to send (can be multiple entities or just one)
opts = {}	`object`	the options to pass to the request (see documentation of javascript `Request`)
returns	`Promise<*>`

remove(data, opts)

APIRequester.js:673

Delete entities (MUST have ids)

remove(data, opts = {})

data	MMO.elements.Entity \| `object` \| `Array`	to send (can be multiple entities or just one). only ids are required
opts = {}	`object`	the options to pass to the request (see documentation of javascript `Request`)
returns	`Promise<*>`