umbraco-restapi

Umbraco-RestApi-JsClient

Javascript Client Library for working with the Umbraco Rest API

Getting started

Install the umbraco-restapi package through npm:

npm install umbraco-restapi

Get access to the api by including it in your project and supplying site and credentials:

var umbraco = require('umbraco-restapi');

//this is bound to change as we roll out proper auth
var siteConfiguration = {
  host: "https://domain.s1.umbraco.io",
  username: "[e-mail]",
  password: "secret"
};

//to use async / await we must run all code inside a async function
async function run(){

    //create a new instance of the client
    var umb = new umbraco.client();

    //then connect to authenticate and generate a token
    //this step will change when authentication is updated 
    await umb.connect(siteConfiguration);

    //client is connected and ready
    
    //get the site
    var site = await umb.content.site();

    //returns {representation, resource};
    console.log("site name: " + site.representation.body.name);

    //returns {representation, resource}
    //representation holds children as embedded resources
    var children = await umb.content.children(site.resource);
    
    //embedded is a dictionary of content with the url as key so fetch all values
    //iterate through the names of all content
    Object.values(children.representation.embedded).forEach(x => {
        console.log(x.name);
    });    
}

//run the async function
run();

Copy the entire code above into a file called app.js and run the file with node:

node app.js

Client

Create as a new and connect using a site configuration using async connect(config)

var umbraco = require('umbraco-restapi');
var client = new umbraco.client();
umb.connect({host,login,password}).then(function() {

  //ready

});

Everthing is Async

All methods are async so must be returned as either a promise or using async/await:

async function run(){
  var content = await client.content.get(1123);
  console.log(content.representation);
}

run();

//or

client.content.get(1123).then(function(response){
  console.log(response.representation);
});

Representation/Resource Return values

All functions return a combination of a representation of the data and a resource which describes where the data comes from.

All methods returning collecions are paged and have a pagesize of 100 set by default.

Representation

Represents the data retrieved and follows the HAL/Api json spec:

{
  body: {
    name: "Hello",
    id: 1234,
    url: "/hello/hello
    properties: {
      bodyText: "World",
      summary: "Such summary"
    }
  },

  //contains links to related urls to call
  links : []

  //contains content collections - used when multiple items 
  //are returned, such as .children, descendants or .search
  embedded: []
}

Resource

A HAL-compatible resource is returned to allow users to follow the provided HAL-links into the API without hardcoding urls in their code.

var content = await client.content.get(1234);
var children = await content.follow('children');

Documentation on link follows are available on: https://github.com/evert/ketting

Content API

Read-only api using published content

Available on the client as client.content - eg client.content.get(1234)

.get(id)

Given a integer id - returns a single content item as {representation, resource}

.site()

returns the first root content item

.rootContent()

returns all root content items

.children(parent)

returns all children below a given parent, parent can be a number a resourceor a options object:

{
  id: 1234,
  page: 0,
  size: 100
}

.descendants(parent)

returns all descendants below a given parent, parent can be a number a resourceor a options object:

{
  id: 1234,
  page: 0,
  size: 100
}

.ancestors(item)

returns all acestors above a given content item, item can be a number a resourceor a options object:

{
  id: 1234,
  page: 0,
  size: 100
}

.search(query)

Searches all published content - query can be string or a options object - the query must a lucene compatible query.

{
  query: 'bodyText:hey AND summary:Jan',
  page: 0,
  size: 100
}

.query(query)

Queries all published content - query can be string or a options object - the query must a XPATH compatible query.

The Id provided is the root of where the query should start

{
  query: '/root/homepage/products',
  page: 0,
  size: 100,
  id: 1234 (optional)
}

.byUrl(url)

Returns a single content item matching the given url - url must be a string

.byTag(query)

Returns a collection of published content tagged with the given tag, query can be either a string or a options object

{
  tag: 'umbraco',
  group: 'news'
  size: 100,
  page: 0
}

---

Media API

Read and write api for all media

Available on the client as client.media - eg client.media.get(1234)

.get(id)

Given a integer id - returns a single media item as {representation, resource}

.create(media)

Creates a new media item - media is a object following the representation syntax:

var media = {
  parent: 1234,
  name: "My new media",
  properties: {
    property: 1234,
    bodyText: "hello!"
  }
}

await client.media.create(media);

.update(id, media)

Updates an exisitng item - id is a number media is an object following the representation syntax:

var media = {
  parent: 1234,
  name: "My new media",
  properties: {
    property: 1234,
    bodyText: "hello!"
  }
}

await client.media.update(id, media);

.delete(id)

Deletes an exisitng item - id is a number

.rootMedia()

returns all root media items

.children(parent)

returns all children below a given parent, parent can be a number a resourceor a options object:

{
  id: 1234,
  page: 0,
  size: 100
}

.descendants(parent)

returns all descendants below a given parent, parent can be a number a resourceor a options object:

{
  id: 1234,
  page: 0,
  size: 100
}

.search(query)

Searches all media - query can be string or a options object - the query must a lucene compatible query.

{
  query: 'umbracoFile:hey AND name:Jan',
  page: 0,
  size: 100
}

---

Members API

Read and write api for all members

Available on the client as client.members - eg client.members.get(1234)

.get(id)

Given a integer id - returns a single member item as {representation, resource}

.create(member)

Creates a new member - member is a object following the representation syntax:

var member = {
  name: "My name is",
  email: "[e-mail]",
  password: "secret",

  properties: {
    property: 1234,
    bodyText: "hello!"
  }

}

await client.members.create(member);

.update(id, member)

Updates an exisitng item - id is a number member is an object following the representation syntax:

var member = {
  name: "Jon Snow,
  properties: {
    property: 1234,
    bodyText: "So cold!"
  }
}

await client.members.update(id, member);

.delete(id)

Deletes an exisitng item - id is a number

.search(query)

Searches all media - query can be string or a options object - the query must a lucene compatible query.

{
  query: 'umbracoFile:hey AND name:Jan',
  page: 0,
  size: 100
}

---

Relations API

Read and write api for relations between media, content and members only

Available on the client as client.relations - eg client.relations.get(1234)

.get(id)

Given a integer id - returns a single relation as {representation, resource}

.create(media)

Creates a new relation item - media is a object following the representation syntax:

var relation = {
  parent: 1234,
  child: 2234
}

await client.relations.create(realtion);

.update(id, relation)

Updates an exisitng relation - id is a number relation is an object following the representation syntax:

var relation = {
  parent: 1234,
  child: 2234
}

await client.relations.update(id, relation);

.delete(id)

Deletes an exisitng relation - id is a number

.children(parent)

returns all child relations of a given parent

.parents(child)

returns all parent relations of a given child