Event Calendar for Jira – REST API

REST API for Event Calendar for Jira allows to easily retrieve, create, and delete data with Our API Platform.

Eligibility to use the apis

An active license for Event Calendar for Jira is required.

Authentication

The Event Calendar for Jira REST API uses an access token for secure authentication. This token must be included in the X-AldevaDigital-Rest-Token header for all API requests.

Generating the Access Token

Access tokens can only be generated by Jira admins. To create an access token, follow these steps:

Log in to your Jira instance with admin privileges.
Navigate to Apps -> Event Calendar in the top panel
Go to Settings.
Select the API Access tab.
Click Generate Token.
Copy the generated token. It expires in 3 months.

Note: Each token is unique and tied to your Jira instance. Keep tokens confidential to prevent unauthorized access.

Using the Access Token in API Requests

Include the token in the X-AldevaDigital-Rest-Token header of your HTTP requests. Below is an example of a request with the access token:

fetch("https://<site-url>/rest-api/1/<resource>", {
    method: "GET",
    headers: {
        "X-AldevaDigital-Rest-Token": "your-access-token-here",
        "Content-Type": "application/json",
    }
});

API base url

The base url for all api calls is

https://jira-apps.aldevadigital.com

HTTP Response Codes

The Event Calendar for Jira REST API uses standard HTTP response codes to indicate the success or failure of requests. Below is a detailed breakdown of the response codes you may encounter while interacting with the API.

Success Codes

HTTP Code	Description	Notes
200	OK	The request was successful, and the response contains the requested data.
201	Created	A new resource was successfully created. The response may include the ID of the created resource.
204	No Content	The request was successful, but there is no content to return (e.g., for `DELETE` requests).

Error Codes

HTTP Code	Description	Notes
400	Bad request	The payload data is invalid.
401	Unauthorized	Access token is invalid. Ensure the `X-AldevaDigital-Rest-Token` header is included and contains a valid token.
403	Forbidden	Access token has been revoked or expired. Generate a new token via Jira → Event Calendar → Settings → API Access.
429	Too Many Requests	Throttling limit for the endpoint has been reached. Wait before retrying the request.

Handling Common Errors

400 Bad request: The request payload includes data format that is invalid. Check the documentation if you’ve formatted the request payload properly.
401 Unauthorized: Double-check the access token in the header. Make sure it is valid and has not been modified or truncated.
403 Forbidden: Generate a new token and update your application to use it.
429 Too Many Requests: Implement exponential backoff to manage retries. Check if your application is exceeding the API rate limits for the endpoint.

By understanding and handling these response codes effectively, you can ensure smooth integration and operation with the API.

Response

The Event Calendar for Jira REST API provides responses that consist of an HTTP status code and, in some cases, a response body. Use these elements to determine the result of your API calls.

Interpreting HTTP Responses

HTTP Response Code: Indicates the success or failure of the request.
HTTP Response Body: Contains additional details about the request’s outcome, such as returned data or error messages.

General Response Patterns:

GET Requests: Typically returns a readable response body containing the requested data.
POST Requests: Returns the ID of the newly created resource in the response body.
PUT, PATCH and DELETE Requests: Returns an HTTP 204 No Content response if the request is successful, without a response body.

Example of a Successful HTTP 200 Response

When a GET request is successful, the API returns a 200 OK status code with a response body. Below is an example of such a response:

{
    "status": true,
    "data": [
        {
            "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "name": "Team Meeting",
            "calendar": "uuid...",
            "start": "2025-01-10T10:00:00Z",
            "end": "2025-01-10T11:00:00Z"
        },
        {
            "id": "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY",
            "name": "Project Review",
            "calendar": "uuid...",
            "start": "2025-01-11T15:00:00Z",
            "end": "2025-01-11T16:00:00Z"
        }
    ]
}

Successful POST Response Example

For a POST request, the API typically returns the ID of the newly created resource:

{
    "status": true,
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

Successful PUT, PATCH or DELETE Response

A successful PUT, PATCH or DELETE request returns an HTTP 204 No Content response, indicating that the operation was completed successfully but no data is returned.

HTTP/1.1 204 No Content

Error Response Example

In the case of an error (e.g., invalid token or request format), the API includes a descriptive error message in the response body:

{
    "status": false,
    "error": "Access token is missing or invalid"
}

By understanding the structure of these responses, you can effectively handle and debug API calls in your application.

API Endpoints

The Event Calendar for Jira REST API provides several endpoints to manage event types, calendars, and individual events. Below is a detailed description of the available endpoints.

Available endpoints: