WARNING

This API is currently under development and can change any time. Do not use for production environments.

Any feedback, bug reports or ideas are welcome.

Current Version

By default, all requests receive the v1 version of the API.

In all API versions, we return an HTTP response header called campaignchain-api-version which indicates the detailed API version your app is actually experiencing (e.g. 1.0.9) - this may be different to the API version you specify in your request due to upgrades.

Authentication

OAuth2 is a protocol that lets external apps request authorization to access the CampaignChain REST API.

Administrators need to create an OAuth server app inside CampaignChain. This can be done under Settings and OAuth Server App. Once an OAuth app was created, the app key and secret can be provided to developers to configure an OAuth client. The user name and password for authentication correspond with a user in CampaignChain.

Endpoints

The root endpoint of the REST API depends on the domain and path to your CampaignChain installation. Throughout this document, we use http://www.example.com as the sample domain indicating where CampaignChain was installed. The full root endpoint is being composed of the domain (plus a path if installed in a sub-directory) and /api/v1 appended to it. Hence, the full sample root endpoint is http://www.example.com/api/v1.

Core

All endpoints of REST APIs that belong to the core functionality of CampaignChain can be accessed directly under /api/v1.

Packages

The endpoints for packages or modules that extend the core, reside under /api/v1/p plus the Composer package name appended as a path. For example:

$curl -i "http://www.example.com/api/v1/p/campaignchain/activity-twitter/statuses/82"

This request provides the data of a specific Tweet managed within CampaignChain. The REST API has been implemented in the Composer package campaignchain/activity-twitter.

HTTP Verbs

Verb	Description
GET	Used for retrieving resources.
POST	Used for creating resources.

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter. Some of them can have multiple values (i.e. they are arrays) and must use []:

$ curl -i "http://www.example.com/api/v1/campaigns.json?fromNow[]=ongoing&fromNow[]=upcoming"

In this example, the ongoing and upcoming values are provided for the fromNow parameter in the query string to retrieve all campaigns that run right now and in the future.

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of application/json.

Parameters are case sensitive.

Module URI Parameter

Many API endpoints take the optional moduleUri parameter. The syntax for its value is a URI composed of (Composer package name)/(module identifier). For example:

• Composer package name: campaignchain/location-facebook
• Module identifier: campaignchain-facebook-user
• Module URI: campaignchain/location-facebook/campaignchain-facebook-user

The module type of the provided module URI must fit the endpoint. For example, a request such as

$ curl -i "http://www.example.com/api/v1/campaigns/?moduleUri[]=campaignchain/location-facebook/campaignchain-facebook-user"

would not return a successful response, because the provided module URI defines a module of type location. Instead, it is supposed to be of type campaign, such as campaignchain/campaign-scheduled/campaignchain-scheduled.

Learn more about the Composer pacakge name.

Format

Request bodies must be sent and responses will be retrieved in JSON.

POST Activities

In POST requests, a package might require data in addition to the one that must be provided for core resources. For example, if a new Twitter post should be created, then the respective endpoint expects to receive data to create the core Activity (e.g. its name) along with the package-specific data (i.e. the Twitter message content).

Such package-specific data must be specified as a child of the related Operation's module name. For example, the campaignchain/activity-twitter package requires the campaignchain/operation-twitter package. In the Operation module's campaignchain.yml configuration file, the module's name is specified as campaignchain-twitter-update-status.

In the REST request, the module's name dashes must be replaced with underscores, which would result in campaignchain_twitter_update_status.

Similarly, the Hooks defined for an Activity module must also be included in the input (e.g. to set the due date). These are defined in the campaignchain.yml configuration file of the respective module. The dashes in their names must be replaced with underscores and the whole name prefixed with campaignchain_hook.

See below an example input for creating a new Twitter status.

{
    "activity":{
        "name":"My Tweet",
        "location":100,
        "campaign":1,
        "campaignchain_twitter_update_status":{
            "message":"Some test status message"
        },
        "campaignchain_hook_campaignchain_due":{
            "date":"2015-12-20T12:00:00+0000"
        },
        "campaignchain_hook_campaignchain_assignee":{
            "user":1
        }
    }
}

Date

All timestamps are returned and must be provided in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

For example:

2015-12-20T12:00:00+0000

The timezone for all timestamps is UTC.

Documentation

In CampaignChain

If you have a CampaignChain instance running in development mode, you can access the instance's REST API documentation by clicking on the developer icon in the header and selecting "REST API Doc". There, you can also access a sandbox for each endpoint where you can try the API live.

Per Resource

For each resource, the respective REST API documentation can be viewed in a browser by appending ?_doc=1 to the endpoint of a CampaignChain installation. For example:

http://www.example.com/api/v1/campaigns?_doc=1

Sample Data

All example requests or inputs provided in the documentation for each endpoint should work with the sample data provided by CampaignChain, Inc.

Resources