You can explore the read-only part of the API (everything retrieved using GET) directly from your web browser. Firefox is particularly well suited for this thanks to its native XML rendering. You can also install JSON View to display JSON responses in a more readable format.

Testing the API

Using curl

You can test the API using the curl command-line tool.

To update (PUT) or create (POST) a JSON resource, use the following commands:

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 {json_resource} is the JSON payload sent to the API to create or update a resource.

Using a REST Client

If you prefer a graphical interface, you can use any REST client to test the Eventmaker API.

Swagger documentation is available here:

https://app.eventmaker.io/swagger

Authentication

API requests are always performed on behalf of an existing Eventmaker user. There is no dedicated API user.

For example, if you authenticate as john@company.org, you will only be able to access the events and resources that John is authorized to manage.

Authentication is performed using an authentication token (auth_token), which can be found in your user profile once you are logged into Eventmaker.

Simply append the auth_token as a query parameter to every request.

Example:

GET /api/v1/events.json?auth_token=YOUR_API_TOKEN

This request retrieves all events you are allowed to manage.

Format

The Eventmaker API supports both JSON and XML.

Simply append .json or .xml to the requested resource URL.

Example (JSON):

GET /api/v1/events.json?auth_token=YOUR_API_TOKEN

Response:

HTTP/1.1 200 OK
 Content-Type: application/json; charset=utf-8

Example (XML):

GET /api/v1/events.xml?auth_token=YOUR_API_TOKEN

Response:

HTTP/1.1 200 OK
 Content-Type: application/xml; charset=utf-8

Throughout this documentation, .format refers to either .json or .xml.

When creating (POST) or updating (PUT) resources, you must specify the appropriate Content-Type header.

JSON example:

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

XML example:

POST /api/v1/events/{event_id}/guests.xml?auth_token=YOUR_API_TOKEN Content-Type: application/xml; charset=utf-8

Response:

HTTP/1.1 201
 Created Content-Type: application/xml; charset=utf-8

API Status Codes

The API uses standard HTTP status codes.

200 OK – Successful GET request.
201 Created – Successful POST request.
204 No Content – Successful PUT or DELETE request.
400 Bad Request – Check your request payload.
403 Forbidden – Your auth_token may be missing or invalid.
404 Not Found – The requested resource does not exist.
406 Not Acceptable – The .format extension or the Content-Type header may be missing.
422 Unprocessable Entity – Check your request payload. The JSON or XML may be malformed.

Error Messages

If the API returns a status code outside the 2xx range, an error occurred.

The response body provides additional information about the cause of the failure.

JSON

General error:

DELETE /api/v1/events.json

// 404 Not Found 
{
   "error": "No API endpoint found at /api/v1/events and method DELETE" 
}

Validation errors returned when creating (POST) or updating (PUT) a resource:

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 examples above:

<!-- 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>

Introduction - Eventmaker REST API

Testing the API

Using curl

Using a REST Client

Authentication

Format

API Status Codes

Error Messages

JSON

XML