The betterplace.org API Version 4

This is the latest API for betterplace.org. It's a REST-style API that returns JSON for serialization. It incorporates some ideas from hypermedia APIs such as the link structure.

Please provide feedback

Please don't hesitate to send feedback about the API and this documentation to [email protected].

Table of content

General information

General information ↓ below
Changelog
Request Parameter Format ↓ below
Addressing the locale of a resource ↓ below
Pagination ↓ below
HTML Sanitization of string attributes ↓ below
Picture formats ↓ below
HTTP Status Codes ↓ below
Error Messages ↓ below
Known issues ↓ below
API Client Libraries ↓ below
Code examples ↓ below
Example apps ↓ below

General information

The API is https only, all non-https requests will be redirected accordingly
The response format is JSON
We support Cross-origin resource sharing (CORS), so no proxy or JSONP is required
Authentication: Most API calls are public. Some client API features require authentication. Learn more
The data of betterplace Users is not part of the API at this moment.

Request parameter format

The order and facets request parameters accept multiple key-value pairs. We use the same convention as the Google Static Maps API V2.

Example: foo:bar|lorem:ipsum

This way you may specify a primary and secondary sort order such as order=rank:DESC|created_at:DESC, which will cause higher ranked objects to come first and more recently created objects to come first if they have equal rank.

Split key and value by a colon :
Split multiple key-value pairs by a pipe | (%7C)
URL-encode all params, so the pipe becomes %7C
Note that for readability reasons we don't URL-encode the params in this documentation

Addressing the locale of a resource

Some resources offer translated content. To access the translated content you need to set the lang-prefix in the API URL. api_v4/de/projects/… returns the German translations while api_v4/en/projects/… return the English ones. Non-translated content will fall back to the original content language. We currently support content with German and English translations.
The same pattern applies to creating resources for a specific language.

Pagination

All list requests can be paginated with the following parameters.

Parameter	Description	Default
`page`	Used to paginate through the list	1
`per_page`	The number of entries per page	20

The per_page parameter is capped at 200. Any higher value for per_page grants at most 200 results.

The following attributes are returned in all list view responses:

Attribute	Description	Example
`total_entries`	Count of all entries	23
`offset`	The number of entries that are skipped before the current listing begins, `= max(page - 1, 0) * per_page`	0
`total_pages`	Count of all pages, based on `per_page`	42
`current_page`	What page we are on	1
`per_page`	Number of entries per page	20

Sanitization

Every string attribute returned in a JSON document is sanitized HTML. By default only a, b, br, em, i, li, ol, p, strong, ul tags are allowed. If an attribute allows for a different set of tags it is specified in the documentation of this field under the "Response Attributes" headline. We might adapt the allowed this set of tags at any time without further notice, e.g. to avert upcoming security problems.

Picture formats

Please note that all over the API only the original image version will always be available. There are additional image versions for various entities, e.g. fill_960x500 for projects. You can use these versions, but they might change in the future!

HTTP Status Codes

The following HTTP result codes can be returned:

HTTP Code 200 if all is good and HTTP Code 304 if this good thing has not been modified (based on ETag).
HTTP Code 201 if a resource was created successfully.
HTTP Code 202 if a resource was successfully submitted for delayed processing.
HTTP Code 400 if a requested resource could not be created or updated, if the submitted data was invalid.
HTTP Code 401 if a resource requires client authentication but the authentication failed.
HTTP Code 403 if a resource requires client authentication but no client was authenticated.
HTTP Code 404 if a requested resource could not be found. Also used for projects that are not part of a given client scope.
HTTP Code 422 if the submitted resource could not be accepted due to erroneous parameters.
HTTP Code 500 if a software error on the server was encountered.
HTTP Code 503 if the server is unavailable due to high load.

Error Messages

If an error occurs, a JSON response message is returned with a name and reason (optional). Clients that use the betterplace.org staging environment will also see a backtrace and message property.

Example:

{
  "name": "GeneralError",
  "status": "not_found",
  "status_code": 404,
  "reason": "Record Not Found",
  "backtrace": [
    "/path/to/file:23:in 'method'",
    "/path/to/file:42:in 'method2'"
  ],
  "message": "Couldn't find Project with id=666",
  "links":[]
}

If errors occur during the creation process of a resource, the answer will contain helpful information about how to resolve the issue. Please note that this information is not meant to be used in your application directly but only for your development process. We might change the specs for the error response at any time without further notice.

Example with validation errors:

{
  "name": "GeneralError",
  "status": "unprocessable_entity",
  "status_code": 422,
  "reason": "Cannot Process Submitted Data",
  "backtrace": [
    "/path/to/file:23:in 'method'",
    "/path/to/file:42:in 'method2'"
  ],
  "message": "First name Dies ist ein Pflichtfeld",
  "errors": { "first_name": [ "Dies ist ein Pflichtfeld." ] },
  "links":[]
}

Known issues

Please contact [email protected] for more information

Documentation: Not all resources have a documentation URL as part of the JSON response
Documentation: The response table does not show the root documentation for response elements with sub-elements (for example carrier.name is documented but carrier is not)

API Client Libraries

While we currently do not offer any official client API libraries, Duilio Ruggiero implemented the prototypical ruby client bettery.

We would love to hear from you if you plan to use/extend bettery or implement your own client and publish the code.

Code examples

Using the API with PHP
WordPress Plugin by freifunk which shows the freifunk projects as a table
Please send us your code examples to [email protected]

Example apps

"Deutsch-Tansanische Partnerschaft e.V." uses this API to present their betterplace.org projects right on their website: Project list, Project details
"Förderverein Freie Netzwerke e.V." uses this API to present their betterplace.org projects right on their website.
"Alfred-Kunze-Sportpark" uses this API to present all needs for their one betterplace.org project right on their website.
"Earthship Tempelhof" uses this API to embed our integrated donation form (iframe) alongside information about the project status.
Please send us your sites to [email protected]

Client API

This API provides special features for companies and organisations as part of the services offered by our betterplace solutions. This client access requires a special contract. Please contact us with your questions.

Client Projects

Clients projects are projects on betterplace.org that are associated with an api client as part of the services that betterplace.org provides for companies. This way clients can control what projects are visible on their external platform.

Some URLs have a special scope for clients. Examples:

/clients/example_client/projects will only show projects of the client "example_client"
/clients/example_client/tags/rainforest/projects will only show projects of the client "example_client" that are tagged with "rainforest".

If you request data for a project that is not part of the client projects, the API will return an HTTP error code 404.

Client Volunteering Offers

Clients volunteering offers are volunteering offers on betterplace.org that are associated with an api client as part of the services that betterplace.org provides for companies. This way clients can control what volunteering offers are visible on their external platform.

It works the same way as with projects, see above ("Client Projects").

Client Authentication

Some features of the betterplace.org client API require your authentication.

Please use your API Credentials to authenticate with HTTP Basic Authentication username and password.
Please use the special scope for clients that is described above.

Username, password and client scope are provided as part of a contract with our betterplace solutions.

Usage example

The local German newspaper "Trierischer Volksfreund" has its own donation portal at "Meine Hilfe zählt". All data is pulled from this API. They also use the betterplace.org whitelabel donation form, which is another service betterplace.org provides for clients.

API V1, V2, V3

betterplace.org has three deprecated APIs. For more information contact [email protected].

About betterplace.org

Learn more about betterplace at https://www.betterplace.org/c/about-us/

License of this documentation

See the license file.

Shareable URL

Share these docs with your friends and family: api-docs.betterplace.org

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

betterplace / betterplace_apidocs

Labels

Projects that are alternatives of or similar to betterplace apidocs

The betterplace.org API Version 4

Please provide feedback

Table of content

General information

Public API

Client API

Organisation API

General information

Request parameter format

Addressing the locale of a resource

Pagination

Sanitization

Picture formats

HTTP Status Codes

Error Messages

Known issues

API Client Libraries

Code examples

Example apps

Client API

Client Projects

Client Volunteering Offers

Client Authentication

Usage example

API V1, V2, V3

About betterplace.org

License of this documentation

Shareable URL