Repository navigation
Campaigns
Campaigns represent a financial goal that we're trying to accomplish, sometimes within a set timeframe. Campaigns can be anything from "keep the project funded" to "add iOS support".
Campaigns appear as follows:
{
"id": uint64,
"title": string,
"description": string,
"goal": int,
"amount": int,
"auxilliary": bool,
"starts": datetime,
"ends": datetime,
"achieved": bool
}
Mutable properties are properties that can be modified through interactions with the API.
- title: a brief, user-facing value to identify the Campaign. Can be something like "March Server Expenses" or "iOS Support".
- description: a longer textual explanation of what the money is being raised for.
- goal: the amount, in cents ($1 = 100) that needs to be raised for this Campaign to be fulfilled.
- auxilliary: whether this Campaign is an auxilliary Campaign or not. Auxilliary Campaigns are CAmpaigns whose goals are not required to be met for the continuing functioning of the service. An auxilliary goal could be something like adding support for a new platform; a non-auxilliary goal could be something like paying the server bills for a certain month.
- starts: the date and time the Campaign begins, expressed as RFC 3339. Note that Payments cannot be applied to Campaigns before the Campaign starts. This value is optional; omit it for Campaigns that should start immediately.
- ends: the date and time the Campaign ends, expressed as RFC 3339. Note that Payments cannot be applied to Campaigns after the Campaign ends. This value is optional; omit it for Campaigns that have no time constraint.
Immutable properties are properties that are created and modified only by the system; there is no way to modify them through the API.
- id: a unique, immutable identifier for this Campaign.
- amount: the amount, in cents ($1 = 100) that has been raised so far.
- achieved: whether the Campaign has been achieved or not. For Campaigns with an ends date and time, this value is determined at that time. For Campaigns with no time constraint, this value is determined when the Campaign total passes the amount value.
This request does not require authentication. If the request is not authenticated, only Campaigns whose starts property refers to a time in the past will be returned. If the request is authenticated with administrative credentials, all Campaigns will be returned.
GET /campaigns
The following URL parameters are accepted when listing Campaigns, and will filter accordingly:
- after: the ID of a Campaign. Only Campaigns after that Campaign will be returned.
- before: the ID of a Campaign. Only Campaigns before that Campaign will be returned.
- count: the maximum number of Campaigns to return, as an integer. Defaults to 20, with a maximum of 100.
-
achieved: if present and set to
true, only Campaigns that have been achieved will be returned. If present and set tofalse, only Campaigns that have not been achieved will be returned. If not present, all Campaigns will be returned. -
current: if present and set to
true, only Campaigns that are currently running will be returned. If present and set tofalse, only Campaigns that are not currently running will be returned. If not present, all Campaigns will be returned. -
auxilliary: if present and set to 'true', only auxilliary Campaigns will be returned. If present and set to
false, only non-auxilliary Campaigns will be returned. If omitted, all Campaigns will be returned.
This request sets the Last-Modified header to the last starts or ends property of the Campaigns returned, whichever is greater while still being prior to the current date and time.
The Content-Type of this request will be campaigns/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be campaigns/json.
This request returns a list of Campaign resources as a JSON array:
{
"code": 200,
"msg": "Successfully retrieved a list of campaigns",
"campaigns": [
{
// See the Campaign Resource for the contents of this part
},
{
// See the Campaign Resource for the contents of this part
}
]
}
In the event no payments are to be returned, an empty array will be returned.
This request does not require authentication. If the request is not authenticated, only Campaigns whose starts property refers to a time in the past will be returned; all others will result in a Campaign Not Found Error. If the request is authenticated with administrative credentials, all Campaigns will be returned.
GET /campaigns/{id}
This request sets the Last-Modified header to the starts or ends property of the Campaign returned, whichever is greater while still being prior to the current date and time.
The Content-Type of this request will be campaigns/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be campaigns/json.
This request returns a list of Campaign resources as a JSON array. The array will only have one item:
{
"code": 200,
"msg": "Successfully retrieved campaign",
"campaigns": [
{
// See the Campaign Resource for the contents of this part
}
]
}
This request requires administrative credentials.
POST /campaigns
The request body should be a JSON object containing a Campaign Resource. Only the Mutable Properties will be used; the rest will be ignored.
A sample request body:
{
"campaign": {
"title": "March Operating Costs",
"description": "A very long description about what operating costs entail, blah blah blah.",
"goal": 24316,
"auxilliary": false
}
}
The request responds with the Campaign that was created.
This request sets the Last-Modified header to the current date and time.
The Content-Type of this request will be campaigns/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be campaigns/json.
This request returns a list of Campaign resources as a JSON array. The array will only contain the Campaign that was created:
{
"code": 201,
"msg": "Successfully created campaign",
"campaigns": [
{
// See the Campaign Resource for the contents of this part
}
]
}
This request requires administrative credentials.
PUT /campaigns/{id}
The request body should be a JSON object containing attributes from a Campaign Resource. Only the Mutable Properties will be used; the rest will be ignored. Properties not included will default to their current values.
A sample request body:
{
"campaign": {
"goal": 48716
}
}
Thie request responds with the Campaign that was modified.
This request sets the Last-Modified header to the current date and time.
The Content-Type of this request will be campaigns/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be campaigns/json.
This request returns a list of Campaign Resources as a JSON array. The array will only contain the Campaign that was modified:
{
"code": 200,
"msg": "Successfully updated campaign",
"campaigns": [
{
// See the Campaign Resource for the contents of this part
}
]
}
This request requires administrative credentials.
DELETE /campaigns/{id}
This request sets the Last-Modified header to the current date and time.
The Content-Type header of this request will be campaigns/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be campaigns/json.
This request returns a list of Campaign Resources as a JSON array. The array will only have one item—the Campaign that was just deleted:
{
"code": 200,
"msg": "Successfully deleted the campaign",
"campaigns": [
{
// See the Campaign Resource for the contents of this part
}
]
}