Eventmaker Rest API
Eventmaker API documentation - version 1
The Eventmaker API is implemented as vanilla JSON and XML over HTTP using all four verbs (GET/POST/PUT/DELETE). Every resource, like Event, Guest, or Check-in, has their own URL and are manipulated in isolation. In other words, we’ve tried to make the API follow the REST principles.
You can explore the view part of the API (everything that’s fetched with GET) through a regular browser. Using Firefox for this is particularly nice as it has a good, simple XML renderer. You can also get a nice view of the JSON version of the API by installing JSON View.
Testing the API
With curl
You can test Eventmaker API using the command line tool curl
. If you need to update (PUT
) or create (POST
) a JSON resource, use the following template:
curl -X PUT -H "Content-Type: application/json" -d "{json_resource}" {url}.json?auth_token=YOUR_API_TOKEN
curl -X POST -H "Content-Type: application/json" -d "{json_resource}" {url}.json?auth_token=YOUR_API_TOKEN
Where the {json_resource}
is the payload to send to the API to create/update a resource.
With a REST client
If you prefer to test the API with a more visual tool, you can use REST Client, an open-source debugger for RESTful web services, like Eventmaker API! A handy Firefox add-on is available, and the Chrome and Safari extensions are on the way.
API Endpoints
A Swagger documentation is available here: https://app.eventmaker.io/swagger
Authentication
When you’re using the API, it’s always through an existing user in Eventmaker. There’s no special API user. So when you use the API as “[email protected]”, you get to see and work with what John is allowed to. Authenticating is done with an authentication token, which you’ll found in your user profil (you must be logged in).
Then you just need to append the auth_token
as a query parameter of the URL. For instance, you can retrieve a JSON array of all the events you manage by issuing the following request:
GET /api/v1/events.json?auth_token=YOUR_API_TOKEN
Format
The Eventmaker API supports both XML and JSON. You can choose the format you prefer by simply appending .xml
or .json
at the end of the resource URL you query.
Request
GET /api/v1/events.json?auth_token=YOUR_API_TOKEN
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
And for the XML version:
Request
GET /api/v1/events.xml?auth_token=YOUR_API_TOKEN
Response
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
In the endpoints documentation, we’ll use .format
to refer to .xml
or .json
.
When you want to write some data to the API with POST
(creation) or PUT
(update), you’ll need to specify a content-type request header.
Request
POST /api/v1/events/{event_id}/guests.json?auth_token=YOUR_API_TOKEN
Content-Type: application/json; charset=utf-8
Response
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
And for the XML version, you get the idead.
API Return Codes
The API uses the following HTTP status code in the response. Pay attention to them as they will tell you if an error occurred.
200 OK - For any
GET
method which succeds.201 Created - For any
POST
method which succeds.204 No Content - For any
PUT
orDELETE
method which succeds.400 Bad Request - Check your request body.
403 Forbidden - You might have forgotten the
auth_token
.404 Not Found - The resource does not exist.
406 Not Acceptable - You might have forgotten the
.format
or the requestContent-Type
.422 Unprocessable Entity - Check your request body, the JSON or XML might be malformed.
Error messages
If you don’t receive a 2xx
HTTP status code in the response, it means that there is an error. You can look at the response body to get more insight about why your API call was not successful.
JSON
If there is a general error, we’ll send you this:
DELETE /api/v1/events.json
// 404 Not Found
{
"error": "No API endpoint found at /api/v1/events and method DELETE"
}
Now if there is an error with the payload provided to create (POST
) or update (PUT
) a resource, we’ll detail the validation errors like this:
HTTP Request
POST /api/v1/events/{event_id}.json
Content-Type: application/json; charset=utf-8
{ "first_name": "Sébastien", "company_name": "Eventmaker" }
// 422 Unprocessable Entity
{
"errors":
{
"uid":
[
"is invalid",
"can't be blank"
],
"guest_category_id":
[
"can't be blank"
],
"last_name":
[
"should be set, or at least one other element of identity: email, company or uid."
]
}
}
XML
For the same exemple above, you will have the following responses:
<!-- 404 Not Found -->
<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>No API endpoint found at /api/v1/events and method DELETE</error>
</errors>
<!-- 422 Unprocessable Entity -->
<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>Guest Uid is invalid</error>
<error>Guest Uid can't be blank</error>
<error>Guest Category can't be blank</error>
<error>Last Name should be set, or at least one other element of identity: email, company or uid.</error>
</errors>
Last updated
Was this helpful?