API Documentation

Introduction

The myCerfa API lets you retrieve, add and modify application data. We use standard HTTP methods for each of those actions.

• GET to retrieve
• POST to create
• POST to modify

EVERY CALL starts with /api/v1

For example, if you want to retrieve the donors list, the URL looks like this :

https://mycerfa.com/api/v1/donors

If your want to retrieve the data of a donor with the ID 123, the final built URL must be :

https://mycerfa.com/api/v1/donors/123

Requirements

All API access is over HTTPS, and accessed from the mycerfa.com domain

All data is sent and received as JSON.

Authentification

From your server, set up api-key HTTP headers to provide the Access Token. The api-key is the Api Key Secret you can find in your App’s general settings You authenticate to the API by providing your Access Token in the header request.

A wrong Api Key will return 401 Unauthorized.

curl -X GET https://mycerfa.com/api/v1/ \
	-H "api-key: APP_ID" \

 

Status Codes

myCerfa conform to standards regarding HTTP status codes to indicate success or failure of a request:

• 200: OK, The requested object exist.
• 201: Created, the object has been created.
• 400: Bad Request, required parameters are missing.
• 401: Unauthorized, Your App ID, Access Token is missing or invalid.
• 404: Not Found, the requested object doesn’t exist.

Response Format

GET responses format is as follows:

{
 "data": [],
 "paging": [],
 "error": "",
 "msg": "",
 "status": ""
}

Name	Type	Description
data	Number or Array	Number when a POST is successful. array when a GET is succesful
paging	Array	Pagination Array, see below
error	Boolean	true if error / false if not
msg	String	display a message when error is true
status	Integer	request status code, see above

Pagination

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the limit and offset query parameters. You can only increase the limit parameter to 30 results.

$curl https://mycerfa.com/api/v1/donors?offset=10&limit=50

Result list will send you a meta section in the response which defines:

• Your current limit value
• Your current offset value
• The query string of the next page
• The query string of the previous page

paging: {
 limit: 30,
 next: "?limit=30&offset=60",
 offset: 30,
 previous: "?limit=30&offset=0"
}

All GET requests retrieving lists can take these optional parameters

• limit (integer, optional)
• offset (integer, optional)