-
Notifications
You must be signed in to change notification settings - Fork 0
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
}
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.
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.
-
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 campaigns are to be returned, an empty array will be returned.
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_INVALID_FORMAT | after | The after parameter specified was not a valid ID. |
| 400 | ERROR_INVALID_FORMAT | before | The before parameter specified was not a valid ID. |
| 400 | ERROR_INVALID_FORMAT | count | The count parameter specified was not a valid integer. |
| 400 | ERROR_TOO_SHORT | count | The count parameter specified was too low. |
| 400 | ERROR_TOO_LONG | count | The count parameter specified was too high. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. |
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
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | id | No campaign ID was specified. |
| 400 | ERROR_INVALID_FORMAT | id | The campaign ID specified was not a valid ID. |
| 404 | ERROR_NOT_FOUND | id | The campaign specified was not found. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. |
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
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 403 | ERROR_ACCESS_DENIED | The authenticating user does not have access to create campaigns. | |
| 400 | ERROR_BAD_REQUEST_FORMAT | The request body was not a valid JSON object. | |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 400 | ERROR_MISSING_PARAM | campaign | No campaign field was supplied in the request object. |
| 400 | ERROR_MISSING_PARAM | campaign.title | No title was supplied in the campaign object. |
| 400 | ERROR_MISSING_PARAM | campaign.description | No description was supplied in the campaign object. |
| 400 | ERROR_MISSING_PARAM | campaign.goal | No goal was supplied in the campaign object. |
| 400 | ERROR_MISSING_PARAM | campaign.auxilliary | No auxilliary status was supplied in the campaign object. |
| 400 | ERROR_TOO_SHORT | campaign.goal | The campaign goal was too low. |
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
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 403 | ERROR_ACCESS_DENIED | The authenticating user does not have access to update campaigns. | |
| 400 | ERROR_BAD_REQUEST_FORMAT | The request body was not a valid JSON object. | |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 400 | ERROR_MISSING_PARAM | campaign | No campaign field was present in the request object. |
| 400 | ERROR_MISSING_PARAM | id | No campaign ID was specified. |
| 400 | ERROR_INVALID_FORMAT | id | The specified campaign ID was not a valid ID. |
| 404 | ERROR_NOT_FOUND | id | The specified campaign was not found. |
| 400 | ERROR_TOO_SHORT | campaign.goal | The campaign goal was too low. |
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
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | id | No campaign ID was specified. |
| 400 | ERROR_INVALID_FORMAT | id | The specified campaign ID was not a valid ID. |
| 404 | ERROR_NOT_FOUND | id | The specified campaign was not found. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. |