Javascript Client SDK

Class: ResourcefulEndpoint

ResourcefulEndpoint

ResourceFulEndpoint is the main interaction class against sequoia MDS endpoints. This is what you'll be using to present data to users, for example content items, registered users etc.

This class should not be used directly, but should instead be obtained from ServiceDescriptor#resourcefulEndpoint

<private> new ResourcefulEndpoint(resourceful)

Parameters:
Name Type Description
resourceful Object

the Sequoia descriptor part that describes this endpoint
Source:
Returns:
Type
ResourcefulEndpoint
Example
// `contents` is used in the rest of the examples as our reference
// to a ResourcefulEndpoint
let contents;

client.login('username', 'password').then(session => {
  client.service('metadata').then(service => {
    // Get a resourceful endpoint (this is synchronous as the service passed
    // all the necessary data):
    contents = service.resourcefulEndpoint('contents');
    // whatever
  });
});

Members

batchSize :number

Get the batchSize from the descriptor's storeBatch operation. This is how many resources can be saved at once when saving a ResourceCollection

Type:
  • number
Source:

hyphenatedPluralName :string

Get the hyphenatedPluralName from the descriptor. The hyphenated plural name is used to identify what the resourceful endpoint is called. e.g. a camelCased resource (pluralName) like contentSegments will live under an HTTP endpoint of content-segments

Type:
  • string
Source:

pluralName :string

Get the pluralName from the descriptor. The plural name is used to identify the content array from the JSON response from Sequoia. e.g. for assets, the response will be of the form:

{
  assets: [ asset resource, asset resource ... ],
  linked: [ linked resource, linked resource ... ],
  meta: { ...meta info }
}
Type:
  • string
Source:

relationships :object

Get the relationship info from the descriptor.

Type:
  • object
Source:
Example
contents.relationships

// Returns:

{
  "children": {
    "description": "The associated child contents",
    "type": "indirect",
    "resourceType": "contents",
    "filterName": "withParentRef",
    "fields": [
      "ref",
      "title",
      "parentRef",
      "type"
    ],
    "batchSize": 10,
    "name": "children"
  },
  "assets": {
    "description": "The associated assets",
    "type": "indirect",
    "resourceType": "assets",
    "filterName": "withContentRef",
    "fields": [
      "ref",
      "name",
      "contentRef",
      "type",
      "url",
      "fileFormat",
      "title",
      "fileSize",
      "tags"
    ],
    "batchSize": 10,
    "name": "assets"
  }
}

serviceName :string

Get the serviceName from the descriptor.

Type:
  • string
Source:

singularName :string

Get the singularName from the descriptor. The singular name is used to identify what the specific resourceful resource is identified as.

Type:
  • string
Source:

Methods

<async> all(criteria, options)

The same as ResourcefulEndpoint#browse but will fetch all pages as a single ResourceCollection

Parameters:
Name Type Description
criteria string | Query

A query string to append to the request
options object

fetch options
Source:
See:
Returns:
Type
Promise

browse(criteria, options)

Perform a browse (a GET for all items on this resourceful endpoint, with optional criteria). The collection returned is the first page of results as specified by perPage (or the Resourceful default e.g. 100)

Parameters:
Name Type Description
criteria string | Query

A query string to append to the request
options object

fetch options
Source:
See:
  • Trasport#get
Returns:
Type
Promise

<private> criteriaToQuery(criteria)

Return a query string to append to the HTTP call. Will default to appending ?owner=<owner>

Parameters:
Name Type Argument Description
criteria string | Query <nullable>

A (potential) query string to append to the request
Source:
Returns:
Type
string

destroy(resource, options)

Destroy (perform an HTTP DELETE for) an existing item

Parameters:
Name Type Description
resource Object

An Object corresponding to the resouce you wish to delete
options object

fetch options
Source:
See:
Returns:
Type
Promise

<private> endPointUrl(ref, criteria)

Get the full URL to the resourceful endpoint/item we will send the request to

Parameters:
Name Type Argument Description
ref string <nullable>

An optional unique ref for performing actions on a unique item (rather than browsing)
criteria string | Query <nullable>

A (potential) query string to append to the request
Source:
See:
Returns:
Type
string

newResource(data)

Obtain a new Resource for this endpoint. A new resource is something that has not yet been created remotely.

The owner property will be pre-populated with the current tenancy. Provding a a value for this will override the current tenancy. This is useful when using root tenancy but populating data on behalf of non-root tenancies. See Client#setTenancy for more information.

When a name property is provided, the ref (unique id) of this resource will also be populated. This is useful for allowing linking different kinds of resources together (see Resource#link) before saving the resources.

There is a potential that names you choose will conflict with already stored resources. In this case, your changes will override the remote resource. See the below example for how to handle these situations.

Parameters:
Name Type Description
data Object

data to populate the Resource with

Properties
Name Type Argument Description
owner string <optional>

Defaults to the current tenancy name
Source:
Returns:
Type
Resource
Examples

Create a new resource

const contentItem = contents.newResource({
 name: 'my-new-content',
 title: 'something',
 synopsis: 'a really long synopsis'
});

// You can now call methods on it, for example, a usual flow for creating
// a Resource would be:

contentItem.validate()
.then(() => contentItem.save())
.then(() => {
  // Success, do something (redirect to a new view?)
}).catch((error) => {
  // Validation error (from Resource object or the server), show the user what went wrong
});

Update or create a piece of content

const potentiallyNewContentItem = contents.newResource({
 name: 'my-potentially-new-content',
 title: 'something new',
 synopsis: 'a really long synopsis'
});

function findOrCreateResource(resourceful, data) {
  return resourceful.readOne(`${resourceful.owner}:${data.name}`).catch(() => resourceful.newResource(data));
}

// You can now call methods on it, for example, a usual flow for creating
// a Resource would be:

findOrCreateResource(contents, potentiallyNewContentItem)
.then((contentItem) => {
  // Update with new data in case it was an existing resource
  Object.assign(contentItem, potentiallyNewContentItem);
  contentItem.duration = 'PT75M';

  return contentItem.save())
.then(() => {
  // Success, do something (redirect to a new view?)
}).catch((error) => {
  // Validation error (from the server), show the user what went wrong
});

newResourceCollection(data)

Create a new ResourceCollection for this endpoint.

Useful for creating many resources for ingest.

Parameters:
Name Type Description
data Array.<Object>

data to populate the ResourceCollection with
Source:
Returns:
Type
ResourceCollection
Example

Create a new resource

const contentItems = contents.newResourceCollection([{
 name: 'one',
 title: 'something',
 synopsis: 'a really long synopsis'
},
{
 name: 'two',
 title: 'something else',
 synopsis: 'another really long synopsis'
}]);

contentItems.validate()
.then(() => contentItems.save())
.then(() => {
  // Success, do something (redirect to a new view?)
}).catch((error) => {
  // Validation error (from a nested Resource object or the server), show the user what went wrong
});

readMany(refs, criteria, options)

Fetch (performs an HTTP GET on) many items, with optional criteria

Parameters:
Name Type Description
refs Array.<String>

The unique references for the items
criteria string | Query

A query string to append to the request
options object

fetch options
Source:
See:
Returns:
Type
Promise

readOne(ref, criteria, options)

Fetch (performs an HTTP GET on) an individual item, with optional criteria

Parameters:
Name Type Description
ref string

The unique reference for this item
criteria string | Query

A query string to append to the request
options object

fetch options
Source:
See:
Returns:
Type
Promise

relationshipFor(relationshipName)

Get the relationship info for relationshipName from the descriptor

Parameters:
Name Type Description
relationshipName string

The name of the relationship e.g. 'assets'
Source:
Throws:
  • Throws when the relationship doesn't exist
Type
Error
Returns:
Type
Object
Example
contents.relationshipFor('categories');

// Returns:

{
  "description": "The associated categories",
  "type": "direct",
  "resourceType": "categories",
  "fieldNamePath": "categoryRefs",
  "fields": [
    "ref",
    "title",
    "parentRef",
    "scheme",
    "value"
  ],
  "name": "categories",
  "batchSize": 10
}

<private> responseToResource()

Turn the first item in the Sequoia response for this endpoint into a Resource. This is a convenience for when operating on individual Resources (read, update, store) where the sequoia response is of the form

{
  <pluralName>: [<Resource>],
  meta: { ... }
}

and we want to just operate on Resource

Source:
Returns:
Type
Resource

store(resource, options)

Store (perform an HTTP POST for) a new item

Parameters:
Name Type Description
resource Resource

A Resource corresponding to the new resource you wish to save
options object

fetch options
Source:
See:
To Do:
  • Validate against the descriptor that this is a valid item to store
Returns:
Type
Promise

update(resource, options)

Update (perform an HTTP PUT for) an existing item

Parameters:
Name Type Description
resource Object

An Object corresponding to the new resouce you wish to save
options object

fetch options
Source:
See:
To Do:
  • Validate against the descriptor that this is a valid item to store
Returns:
Type
Promise