Public Server API
The public server API will be used both to deliver data to the front-end budget application and as a way to exchange data with other servers.
Version 1 of the API is quite simple. There is no authentication and it only supports retrieving data (GET requests). There is also no paging, although that will probably need to be added soon.
To better understand the data structures here, it may be helpful to review the page on Core Data Objects.
The following routes are supported:
| URL | Response |
|---|---|
| /api/v1/organizations | List of organizations |
| /api/v1/organizations/OrgId | Details of organization with id OrgId |
| /api/v1/organizations/OrgId/accounts | List of all accounts used by organization OrgId |
| /api/v1/organizations/OrgId/accounts/AcctId | Details of account AcctId |
| /api/v1/organizations/OrgId/categories | List of all account categories used by organization OrgId |
| /api/v1/organizations/OrgId/categories/CatId | Details of category CatId, including all values |
| /api/v1/organizations/OrgId/datasets | List of all datasets available for organization OrgId |
| /api/v1/organizations/OrgId/datasets/SetId | Details of dataset SetId, including all line item entries. See more details below. |
All responses are JSON objects. All have "message" and a "status_code" members. If the request is successful it will also have a "data" member containing the result. If it is unsuccessful it will instead have an "error" member, which may contain additional detail (in fact it doesn't have more than the message and status code right now).
Here is a successful return for /organizations/1:
{
"message": "Organization Asheville City Government",
"status_code": 200,
"data": {
"id": 1,
"name": "Asheville City Government",
"description": null
}
}
And here is an error return for /organizations/2:
{
"message": "No such organization",
"status_code": 404,
"error": {
"message": "No such organization",
"status_code": 404
},
"data": null
}
Simply trying each of the routes on a server that has been seeded will give you a sense of what the actual data is.
Datasets are the main point of this API and so it shouldn't be surprising that they are more complicated and have more options.
The specification of the route in the table above is slightly oversimplified. In fact, the last part of the path can be a dataset ID or it can be a comma-separated list of dataset IDs, e.g.,
/api/v1/organizations/1/datasets/2,5
will return two full datasets.
Here is the first part of the response to /api/v1/organizations/1/datasets/5. Note that, even if only a single dataset is requested, the data section contains an array, so that the format is identical for single datasets and multiple ones.
{
"message": "Some message",
"status_code": 200,
"data": [
{
"id": 5,
"name": "2010 Actuals",
"type": "actual",
"granularity": "Year",
"year": 2010,
"month": null,
"day": null,
"description": null,
"categoryIdentifiers": [
"Fund",
"Department",
"Division",
"Function",
"Cost Center",
]
"items": [
{
"account": "Compensation - Temp\/Seasonal",
"categories": [
"General Fund",
"Administration Services Dept",
"Governing Body Division",
"General Government",
"No Cost Center"
],
"amount": "-4725.00"
},
...
There are two options that may be used on datasets.
Often only expense data or only revenue data will be wanted and, by default, the dataset request returns all data. To restrict to a particular type, simply add a type, e.g., /api/v1/organizations/1/datasets/5?type=expense.
The allowed values are expense, revenue, asset, liability, equity, and contra-account.
In the example above, the actual names of category types, categories and accounts are interpolated into the dataset, rather than included as IDs. This is intended to reduce the amount of work that has to be done on the client side to begin working with the information, although it does make for a somewhat bulky download.
The alternative is to use the noMapping option. A request of /api/v1/organizations/1/datasets/5?noMapping=true would give the following alternative (same actual items as above):
{
"message": "Some message",
"status_code": 200,
"data": [
{
"id": 5,
"name": "2010 Actuals",
"type": "actual",
"granularity": "Year",
"year": 2010,
"month": null,
"day": null,
"description": null,
"categoryIdentifiers": [
1,
2,
3,
4,
5
]
"items": [
{
"account": 1045,
"categories": [
35,
85,
226,
296,
437
],
"amount": "-4725.00"
},
...
In order to determine the actual names of the accounts and categories, you would also need to query those using the appropriate routes.
To get started, use the API to determine the organization ID and the IDs of the datasets you are interested in. If you are working with the seeded data, the ID of the City of Asheville organization is 1 and there are 5 datasets (2010-2014) with IDs 1-5. So, if you want to work with the 2014 Adopted Budget expense data, the request is:
/api/v1/organizations/1/datasets/1?type=expense
That will give you all the relevant data with all the relevant category and account hierarchy.
To deal with all 5 years of data, modify to:
/api/v1/organizations/1/datasets/1,2,3,4,5?type=expense