API

Every Cloudfier application has a full fledged REST API that provides acccess to 100% of the functionality of the application (data, behaviour, and metadata).

The API supports JSON only. Authentication is currently form-based (with a cookie). Other forms of authentication are planned.

Endpoints

Index (…/api/<app>/)

The root URI for a Cloudfier application. Gives access to the entity and service list resources. Also provides access to the currently logged in user, if any.

All Cloudfier applications have their API base URI in the form:

http://develop.cloudfier.com/services/api/<application-slug>/

Where the application slug is a system-generated string uniquely identifying your application.

Example:

{
  entities: "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit/entities/",
  services: "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit/services/",
  currentUser: {
    profile: {
      uri: "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit/instances/shipit.User/25",
      shorthand: "myuser@myhost.com"
    },
    username: "myuser@myhost.com"
  }
}

Entity index (…/api/<app>/entities/)

Lists all entities in the application.

[{
    "namespace": "expenses",
    "name": "Category",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/entities/expenses.Category",
    "extentUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/instances/expenses.Category/"
}, {
    "namespace": "expenses",
    "name": "Employee",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/entities/expenses.Employee",
    "extentUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/instances/expenses.Employee/"
}, {
    "namespace": "expenses",
    "name": "Expense",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/entities/expenses.Expense",
    "extentUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/instances/expenses.Expense/"
}]

Entity description(…/api/<app>/entities/<package.Class>)

Shows details about a specific entity, including properties, actions, relationships and finders (a.k.a. queries). Also includes a reference to the entity’s extent.

{
    "namespace": "shipit",
    "name": "Issue",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/entities/shipit.User",
    "rootUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/entities/",
    "instances": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue",
    "template": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/_template",
    "actions": [{
        "name": "reportIssue",
        "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/actions/shipit.Issue/reportIssue",
        "enabled": true,
        "instance": false
    }, {
        "name": "release",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "assign",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "suspend",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "start",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "resolve",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "reopen",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "comment",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "addWatcher",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "vote",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "withdrawVote",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "assignToMe",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "steal",
        "uri": null,
        "enabled": null,
        "instance": true
    }, {
        "name": "verify",
        "uri": null,
        "enabled": null,
        "instance": true
    }],
    "finders": [{
        "name": "bySeverity",
        "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/finders/shipit.Issue/bySeverity"
    }, {
        "name": "byStatus",
        "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/finders/shipit.Issue/byStatus"
    }],
    "properties": [{
        "name": "summary",
        "type": "String"
    }, {
        "name": "issueId",
        "type": "Integer"
    }, {
        "name": "issueKey",
        "type": "String"
    }, {
        "name": "reportedOn",
        "type": "Date"
    }, {
        "name": "severity",
        "type": "Severity"
    }, {
        "name": "status",
        "type": "Status"
    }, {
        "name": "resolution",
        "type": "Resolution"
    }, {
        "name": "resolvedOn",
        "type": "Date"
    }, {
        "name": "votes",
        "type": "Integer"
    }, {
        "name": "commentCount",
        "type": "Integer"
    }, {
        "name": "waitingFor",
        "type": "String"
    }, {
        "name": "mine",
        "type": "Boolean"
    }, {
        "name": "free",
        "type": "Boolean"
    }, {
        "name": "description",
        "type": "Memo"
    }],
    "relationships": [{
        "name": "labels",
        "type": "Label",
        "typeUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/entities/shipit.Label"
    }, {
        "name": "project",
        "type": "Project",
        "typeUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/entities/shipit.Project"
    }, {
        "name": "reporter",
        "type": "User",
        "typeUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/entities/shipit.User"
    }, {
        "name": "assignee",
        "type": "User",
        "typeUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/entities/shipit.User"
    }, {
        "name": "comments",
        "type": "Comment",
        "typeUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/entities/shipit.Comment"
    }, {
        "name": "watchers",
        "type": "User",
        "typeUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/entities/shipit.User"
    }, {
        "name": "voters",
        "type": "User",
        "typeUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/entities/shipit.User"
    }]
}

Entity extent (…/api/<app>/instances/<package.Class>/)

Lists all instances of an entity.
You can create new instances by POSTing new instance representations (such as returned by the entity instance template endpoint).

[{
    "typeName": "expenses.Category",
    "values": {
        "name": "Meal"
    },
    "shorthand": "Meal",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/instances/expenses.Category/2",
    "type": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/entities/expenses.Category",
    "links": {
        "expensesInThisCategory": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/instances/expenses.Category/2/relationships/expensesInThisCategory/"
    },
    "actions": {}
}, {
    "typeName": "expenses.Category",
    "values": {
        "name": "Airfare"
    },
    "shorthand": "Airfare",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/instances/expenses.Category/4",
    "type": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/entities/expenses.Category",
    "links": {
        "expensesInThisCategory": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/instances/expenses.Category/4/relationships/expensesInThisCategory/"
    },
    "actions": {}
}, {
    "typeName": "expenses.Category",
    "values": {
        "name": "Lodging"
    },
    "shorthand": "Lodging",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/instances/expenses.Category/6",
    "type": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/entities/expenses.Category",
    "links": {
        "expensesInThisCategory": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/instances/expenses.Category/6/relationships/expensesInThisCategory/"
    },
    "actions": {}
}, {
    "typeName": "expenses.Category",
    "values": {
        "name": "Transportation"
    },
    "shorthand": "Transportation",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/instances/expenses.Category/8",
    "type": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/entities/expenses.Category",
    "links": {
        "expensesInThisCategory": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-expenses/instances/expenses.Category/8/relationships/expensesInThisCategory/"
    },
    "actions": {}
}]

Instance data (…/api/<app>/instances/<package.Class>/<oid>)

Shows details of a specific entity instance. Includes values for all properties, links to related objects, and the enablement state for all actions.

{
    "typeName": "shipit.Issue",
    "values": {
        "summary": "Cannot launch two instances of the application",
        "status": "InProgress",
        "votes": 0,
        "assignee": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.User/10",
            "shorthand": "rafael@abstratt.com"
        },
        "issueId": 31,
        "severity": "Major",
        "resolution": null,
        "commentCount": 2,
        "resolvedOn": null,
        "waitingFor": "416 day(s)",
        "reporter": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.User/2",
            "shorthand": "rperez"
        },
        "project": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Project/12",
            "shorthand": "Cloudfier issues"
        },
        "reportedOn": "2012/08/20",
        "free": false,
        "description": "Cannot launch two instances of the application at the same time.",
        "issueKey": "CLD-31",
        "mine": true
    },
    "shorthand": "Cannot launch two instances of the application",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30",
    "type": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/entities/shipit.Issue",
    "links": {
        "labels": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/relationships/labels/",
        "comments": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/relationships/comments/",
        "voters": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/relationships/voters/",
        "watchers": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/relationships/watchers/"
    },
    "actions": {
        "suspend": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/suspend",
            "enabled": true
        },
        "steal": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/steal",
            "enabled": false
        },
        "assign": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/assign",
            "enabled": false
        },
        "resolve": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/resolve",
            "enabled": false
        },
        "vote": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/vote",
            "enabled": false
        },
        "verify": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/verify",
            "enabled": false
        },
        "addWatcher": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/addWatcher",
            "enabled": true
        },
        "assignToMe": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/assignToMe",
            "enabled": false
        },
        "start": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/start",
            "enabled": false
        },
        "withdrawVote": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/withdrawVote",
            "enabled": false
        },
        "comment": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/comment",
            "enabled": true
        },
        "release": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/release",
            "enabled": false
        },
        "reopen": {
            "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/instances/shipit.Issue/30/actions/reopen",
            "enabled": false
        }
    }
}

List of related objects (…/api/<app>/instances/<package.Class>/<oid>/relationships/<relationship-name>/)

Lists all instances related to a context instance via some relationship. The representation is identical to the one used in the entity extent endpoint.


Finder (…/api/<app>/instances/<package.Class>/finders/<query-name>)

Lists all instances that match the specified query. If the finder operation accepts/expects parameters, they can/must be specified. This endpoint can be invoked via a GET (parameters as URI query parameters) or POST (parameters as slots in a JSON object).

The representation is the same as used in the entity extent.


Service index (…/api/<app>/services/)

Lists all services in the application.

[{
    "namespace": "shipit_plus",
    "name": "EmailService",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/services/shipit_plus.EmailService"
}, {
    "namespace": "shipit_plus",
    "name": "EmailUserNotifierService",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/services/shipit_plus.EmailUserNotifierService"
}]

Service description (…/api/<app>/service/<package.Class>)

Shows details about a specific service.

{
    "namespace": "shipit_plus",
    "name": "EmailService",
    "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/services/shipit_plus.EmailService",
    "rootUri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/services/",
    "events": [{
        "name": "sendMessage",
        "uri": "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit-plus/events/shipit_plus.EmailService/sendMessage",
        "enabled": null,
        "instance": false
    }],
    "queries": []
}

Outbound API

A Cloudfier application not only has an inbound API, but it may also have an outbound API, so it can act as a client issuing requests to external services. The outbound API follows the same API style used in the inbound API (REST using HTTP/JSON).

In order for a Cloudfier application to be able to issue requests to an external service, it must:

  • declare an external service that implements the required interface – this involves declaring the service class using the external modifier, and configure the external service URI in the mdd.properties file
  • inject the external service into the object that needs to access it
  • if the external service does not implement the API style used in Cloudfier applications, you will need to implement a gateway service that converts requests and responses between the API style used in Cloudfier and the API format implemented by the actual service.

Read on Services for more information on how to declare them and inject them into a class property.

The outbound API can perform queries, invoke synchronous operations, and send events asynchronously.

As examples of Cloudfier applications that access external services, see:


How to… in the REST API?

How to determine the currently logged-in user via the REST API?

Issue a GET request for the application index resource. It will include the currently logged in user (if any), including a reference to its user profile, if one exists.
will result in:

How to determine the default values when creating a new object via the REST API?

A form that allows creating a new record in the system will often include default values for some of its fields.
To get the default values, issue a GET request for the template resource. The template resource URL is available from the corresponding entity description. For example:

GET http://develop.cloudfier.com/services/api/<app-slug>/instances/shipit.Issue/_template

will result in:

{
  typeName: "shipit.Issue",
  values: {
    summary: null,
    status: "Open",
    votes: 0,
    assignee: null,
    severity: "Normal",
    resolution: null,
    commentCount: 0,
    resolvedOn: null,
    waitingFor: "0 day(s)",
    reporter: null,
    reportedOn: "2013/06/29",
    free: true,
    description: null,
    mine: false
  },
  shorthand: "Sat Jun 29 07:27:45 UTC 2013",
  uri: null,
  type: "http://develop.cloudfier.com/services/api/demo-cloudfier-examples-shipit/entities/shipit.Issue",
  links: {},
  actions: {}
}

How to determine which actions are applicable for a given entity instance via the REST API?

The entity instance representation includes an ‘enabled’ slot for each action defined on the entity. See the instance data representation.

How to determine which objects can be selected for a relationship or an action parameter for a given entity instance via the REST API?

The entity instance representation includes for each relationship the URI for the domain of that relationship and for every action parameter that is an entity the URI to the domain for that parameter. The user interface should be able to establish a relationship with any of the objects in the domain, or pass as an argument any of the objects from the parameter domain.

How can I make my application issue requests or events to an external service?

Read above on Outbound API.