REST API Cookbook

Getting Started

This guide assumes that you have already installed an HTTP client with which you will be making requests. However, it is highly recommended that you look at our language drivers and you read about the one that you will be using in your application.

Connecting to Gitana

Gitana uses OAuth2 to perform authentication, and as such to connect you will have to perform the authentication handshake manually to connect directly with the rest api. The specifics of this differ depending on what HTTP client you are using, but we have a guide for how to do so using Postman

Samples

Here are some request samples to help you get started. In these scenarios, we assume you've already authenticated with Cloud CMS.

In Gitana, you can have as many repositories as you'd like. And each repository can multiple branches (similar to Git). The first thing you should do is connect and get the branch that you want to work on.

For the purpose of most of these examples, we'll assume the repository ID is 1234567890abcdef1234 and the branch is master.

Get your Repository

GET /repositories/1234567890abcdef1234

Read the master Branch

GET /repositories/1234567890abcdef1234/branches/master

Node Creation

Create a Node

{
    "title": "Custom Article",
    "_qname": "custom:article",
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        },
        "body": {
            "type": "string"
        },
        "categories": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "rating": {
            "type": "number"
        }
    }
}

Create a content instance of this type like this:

POST /repositories/1234567890abcdef1234/branches/master/nodes

Body:
{
    "_type": "custom:article",
    "title": "Article #1",
    "body": "A still more glorious dawn awaits",
    "categories": [
        "category1",
        "category2",
        "category3"
    ],
    "rating": 5
}

Associations

In Cloud CMS, any two nodes can be connected via an association. You can use an out-of-the-box association type, such as a:linked or a:owned or you can create your own.

Let's imagine that we have two articles that look like this:

• Article #1

{
    "_doc": "1234567890abcdef1111",
    "_type": "custom:article",
    "title": "Article #1",
    "body": "a mote of dust suspended in a sunbeam",
    "categories": ["category1", "category2"],
    "rating": 1
}

• Article #2

{
    "_doc": "1234567890abcdef2222",
    "_doc": "",
    "_type": "custom:article",
    "title": "Article #2",
    "body": "harvesting star light",
    "categories": ["category2", "category3"],
    "rating": 2
}

Let's create an association that points from the first article (1234567890abcdef1111) to the second article (1234567890abcdef2222), like this:

POST /repositories/1234567890abcdef1234/branches/master/nodes/1234567890abcdef1111/associate?node=1234567890abcdef2222

You can also find all associations around article1. This will include associations that are INCOMING, OUTGOING and MUTUAL.

GET /repositories/1234567890abcdef1234/branches/master/nodes/1234567890abcdef1111/associations

Or find only the INCOMING associations:

GET /repositories/1234567890abcdef1234/branches/master/nodes/1234567890abcdef1111/incoming

Or find only the OUTGOING associations of type a:linked (node here that the : character is URI encoded):

GET /repositories/1234567890abcdef1234/branches/master/nodes/1234567890abcdef1111/incoming?type=a%3alinked

Create a Folder

In Cloud CMS, folders are just nodes with the f:container feature on them. It must be associated to the root node to be considered part of file folder tree.

POST /repositories/1234567890abcdef1234/branches/master/nodes

Body:
{
    "title": "My Folder"
}

The response will contain a _doc property, which is the ID of the new node.

Next, we will add the f:container feature to the new folder node:

POST /repositories/1234567890abcdef1234/branches/master/nodes/newNodeId/features/f:container

Body:
{}

Finally, we must associate the new folder to the root node, to ensure it is part of the file-folder tree. We first will need to read the root node, as we need to associate our folder with this for it to be part of the file-folder system.

GET /repositories/1234567890abcdef1234/branches/master/nodes/root

The resulting JSON will have a _doc property, which is the ID of the root node. Finally, we will associate this to our folder.

POST /repositories/1234567890abcdef1234/branches/master/nodes/<rootNodeId>/associate?node=<newNodeId>

Body:
{
    "_type": "a:child"
}

Query

Let's now look at querying for content. This makes use of MongoDB's query language to express some pretty powerful queries. We recommend further reading on Query within Cloud CMS.

Let's assume that we have the following:

• Article #1

{
    "_type": "custom:article",
    "title": "Article #1",
    "body": "a mote of dust suspended in a sunbeam",
    "categories": ["category1", "category2"],
    "rating": 1
}

• Article #2

{
    "_type": "custom:article",
    "title": "Article #2",
    "body": "harvesting star light",
    "categories": ["category2", "category3"],
    "rating": 2
}

• Article 3

{
    "_type": "custom:article",
    "title": "Article #3",
    "body": "we are star stuff",
    "categories": ["category3", "category1"],
    "rating": 3
}

Basic Querying

Find all of the nodes that have a category with the value category1.

POST /repositories/1234567890abcdef1234/branches/master/nodes/query

Body:
{
    '_type': 'custom:article',
    'category': 'category1'
}

Pagination

If you have a lot of potential query hits, you'll want to paginate. Here is an example where we return results starting at index 2 and hand back at most 5 results.

POST /repositories/1234567890abcdef1234/branches/master/nodes/query?skip=2&limit=5

Body:
{
    '_type': 'custom:article',
    'category': 'category1'
}

Sorting

Use the pagination option to sort the results as you see fit. Here we sort descending on rating. Node that the sort parameter is { "rating": -1 }, URI encoded

POST /repositories/1234567890abcdef1234/branches/master/nodes/query?sort=%7B%22rating%22%3A-1%7D

Body:
{
    '_type': 'custom:article',
    'category': 'category1'
}

Query for values in a range

Find all of the articles where the rating is greater than or equal to 2.
This demonstrates the power of MongoDB's query language.

POST /repositories/1234567890abcdef1234/branches/master/nodes/query

Body:
{
    '_type': 'custom:article',
    'rating': {
        '$gte': 2
    }
}

Search for Nodes

Let's now look at searching for content. This makes use of Elastic Search's DSL to express some very powerful full text and structured searches. We recommend further reading on Search within Cloud CMS.

We also suggest reading up on Query Strings to understand how you can write searches textually (in addition to structuring them as JSON objects):

Let's assume that we have the following:

• Article #1

{
    "_type": "custom:article",
    "title": "Article #1",
    "body": "a mote of dust suspended in a sunbeam",
    "categories": ["category1", "category2"],
    "rating": 1
}

• Article #2

{
    "_type": "custom:article",
    "title": "Article #2",
    "body": "harvesting star light",
    "categories": ["category2", "category3"],
    "rating": 2
}

• Article 3

{
    "_type": "custom:article",
    "title": "Article #3",
    "body": "we are star stuff",
    "categories": ["category3", "category1"],
    "rating": 3
}

Full Text Search

Find all of the nodes with the word star. Simple enough!

POST /repositories/1234567890abcdef1234/branches/master/nodes/search

Body:
{
    "search": "star"
}