umbraco-restapi
v1.0.20
Published
Javascript library for accessing Umbraco website API
Downloads
6
Readme
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: "[email protected]",
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 resource
or a options object:
{
id: 1234,
page: 0,
size: 100
}
.descendants(parent)
returns all descendants below a given parent, parent can be a number
a resource
or 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 resource
or 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 resource
or a options object:
{
id: 1234,
page: 0,
size: 100
}
.descendants(parent)
returns all descendants below a given parent, parent can be a number
a resource
or 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: "[email protected]",
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