Skip to content

REST API

Easy8 provides a "REST-like" HTTP API that returns JSON or XML. The API reference is available in your Easy8 instance at /easy_swagger (see API reference).

Authentication

For authentication, use your Easy8 API key. You can obtain the API key in Easy8 user account settings.

Easy8 accepts the API key in any of these forms:

  • X-Redmine-API-Key: <api-key> header
  • X-Easy8-API-Key: <api-key> header
  • Authorization: Bearer <api-key> header
  • key=<api-key> query parameter

X-Easy8-API-Key is an Easy8-specific alias for the existing X-Redmine-API-Key header. The bearer form accepts an existing Easy8 API key; JWT bearer authentication remains supported where it is available.

Examples:

curl \
  -H "X-Easy8-API-Key: <api-key>" \
  "https://demo.easy8.com/issues.json"

curl \
  -H "Authorization: Bearer <api-key>" \
  "https://demo.easy8.com/issues.json"

Base URL

The API is served from the address of your Easy8 instance, for example https://demo.easy8.com/issues.json. On-premises, use the address of your server. An administrator must enable the REST API in the administration settings, otherwise requests are rejected.

When to use the REST-like API and GraphQL

Use the REST-like API for server-to-server integrations, where data moves from your system to Easy8 and back.

GraphQL serves the Easy8 front end. Use it if you build your own front-end plugin; see GraphQL API.

Rate limits

Rate limits apply in production and are counted per client IP address:

  • API read requests (JSON or XML format): 150 per minute
  • API write requests: 50 per minute
  • Exports (atom, pdf, csv, doc, xlsx, ics): 10 per 5 minutes

A throttled request receives HTTP status 429 with the headers RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. RateLimit-Reset is the Unix time when the current window ends; retry after it.

On-premises administrators can change the limits with the environment variables EASY_RACK_ATTACK_API_READ_LIMIT, EASY_RACK_ATTACK_API_WRITE_LIMIT and EASY_RACK_ATTACK_EXPORTS_LIMIT. Set the matching *_DISABLED variable, or EASY_RACK_ATTACK_DISABLED, to switch throttling off.

Request and response formats

The API sends and receives JSON and XML. Specify the format in the path of every call:

  • JSON: /easy_contacts.json
  • XML: /easy_contacts.xml

For POST and PUT requests, send the request body in the same format.

Status and error codes

The API returns standard HTTP status codes:

  • 401 UNAUTHORIZED: the credentials are missing or incorrect
  • 403 FORBIDDEN: you do not have access to the resource
  • 404 NOT FOUND: the resource does not exist
  • 406 NOT ACCEPTABLE: the requested format is not supported
  • 422 UNPROCESSABLE ENTITY: the request is well-formed but cannot be processed, for example due to validation errors
  • 429 TOO MANY REQUESTS: you exceeded the rate limit