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 like the link-strukture.
Please don't hesitate to provide any feedback about the API and this documentation at developers@betterplace.org.
Please send an email to product@betterplace.org to subscribe to the api-v4-mailing list to receive service announcements about updates and scheduled downtimes.
-
General information ↓ below
-
Request Parameter Format ↓ below
-
Addressing the locale of a resource ↓ below
-
Pagination ↓ below
-
Picture formats ↓ below
-
HTTP Status Codes ↓ below
-
Error Messages ↓ below
-
Known issues ↓ below
-
API Client Libraries ↓ below
-
Code examples ↓ below
-
Example apps ↓ below
-
Public API
-
Projects 1. Projects List and Search 1. Project Details 1. Project Needs List 1. Project Need Details 1. Project Blog Posts List 1. Project Blog Post Details 1. Project Opinions List 1. Project Opinion Details 1. Project Pictures List 1. Project Picture Details
-
Fundraising Events 1. Fundraising Events List and Search 1. Fundraising Events Details 1. Fundraising Event Opinions List 1. Fundraising Event Opinion Details 1. Fundraising Event Featured Projects List 1. Fundraising Event Forwarding List
-
Volunteering 1. Volunteering List and Search 1. Volunteering Details 1. Volunteering Inquiries
-
Organisations 1. Organisations List 1. Organisation Details
-
MatchingFunds 1. MatchingFunds List 1. MatchingFund Details 1. MatchingFund Projects List
-
FundraisingChallenge 1. Fundraising Challenge Contest Details 1. Fundraising Challenge Contest Results List
-
Client API ↓ below
-
Client Projects ↓ below
-
Client Authentication ↓ below
-
Volunteering List and Search – See client section and "Client Volunteering Offers"
-
Client Projects List and Search – See client section and "Client Projects"
-
Client Project Details – See client section and "Client Projects"
-
Client Blog Posts List – See client section
-
Client Project Opinions List – See client section
-
Organisation API
- The API is https only, all non-https requests will be redirected accordingly
- The response/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 feature require authentication. Learn more
- Users, Companies and Portals are not part of the API at this moment.
The order
and facets
request parameters accept multiple key-value-parameter.
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 secondaray sort order like this
order=rank:DESC|created_at:DESC
, which will cause higher ranked objects to
come first and more recently created objects come first if they have equal
rank.
- Split key and value by a colon
:
- Split multiple key-value-parameter 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
- 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 whileapi_v4/en/projects/…
return the english translated content. Not translated content will fallback to the original content language. We currently support content with german or english translations. - The same pattern applies to creating resources for a specific language.
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 |
Please note that all over the API only the original
version will always be available. There are more image versions
for different entities, e.g. fill_960x500 for projects. You can use these versions, but they might change in the future!
To avoid problems stay tuned and subscribe to the Mailing list for service announcements ↑.
The following HTTP result codes can be returned:
- HTTP Code
200
if all is good and HTTP Code304
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.
If an error occurs, a JSON response messages 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 issues. 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 errors-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":[]
}
Please contact developers@betterplace.org for more information
- Documentation: Not all resources have a documentation-url as part of the json
- 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)
- Blogposts: There is no way yet to filter BlogPosts from PayoutBlogPost
While we currently officially do not offer any 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.
- Using the API with PHP
- WordPress Plugin by freifunk which shows the freifunk projects as a table
- Please send us your code examples to developers@betterplace.org
- The "Deutsch Tansanische Partnerschaft" uses this API to present their betterplace.org projects right on their website: Project list, Project details
- The "Förderverein Freie Netzwerke e.V." uses this API to present their betterplace.org projects right on their website.
- The "Alfred-Kunze-Sportpark" uses this API to present all needs for their one betterplace.org project right on their website.
- The "Earthship Tempelhof" uses this API to embed our integrated donation form (iframe) with more information about the project status.
- Please send us your sites to developers@betterplace.org
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.
Clients projects are projects on betterplace.org that are associated with a client. This way clients can control what projects are visible on their plattform.
Some URLs have a special scope for clients. Examples:
/clients/example/projects
will only show projects of the example-client/clients/example/tags/rainforest/projects
will only show projects of the example-client and 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
.
It is possible to associate volunteering offers with a client in order to control which offers will be shown in the API endpoint. It works analogue to the way projects are treated, see "Client Projects".
Some feature 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 the contract with our betterplace solutions.
The local german newspaper "Trierischer Volksfreund" has it's own donation portal at "Meine Hilfe zählt". All data are pulled from this api. In addition they use the betterplace.org whitelabel donation form, which is another service betterplace.org provides for clients.
betterplace.org has three deprecated APIs. For more information contact product@betterplace.org.
Learn more about betterplace at https://www.betterplace.org/c/about-us/
See the license file.
Share this docs with your friends and family: api-docs.betterplace.org