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 “[e-mail]”, 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 or DELETE 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 request Content-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>