Skip to main content

Crate redmine_api

Crate redmine_api 

Source
Expand description

§redmine-api

API for the Redmine issue tracker

§State of this crate

The crate supports both sync and async usage but the async code is significantly newer so it might not be as well tested.

Most API endpoints are supported and each supported API endpoint is tested with at least one unit test though at this early stage I do make no stability guarantees with regards to parameters that might need to be changed slightly to accommodate variants of the API endpoint I missed (e.g. different filters I am not aware of, the documentation on the Redmine wiki is far from complete).

Any such changes should not take a lot of effort when changing a client when updating this crate though, most likely the existing parameter value would just have to be wrapped in a new Enum.

§Running the tests

The tests run against a live Redmine instance and create (and delete again) projects, issues, groups and other objects on it, so do not run them against a production instance.

They need the following variables, set in the environment or a .env file:

  • REDMINE_URL - the base URL of the Redmine instance
  • REDMINE_API_KEY - the API key of an admin user on that instance
  • REDMINE_VERSION - the version of that Redmine instance (e.g. 6.1.2), used by tests that expect different behaviour depending on the Redmine version

The tests only rely on the default data Redmine loads into a new instance, so a fresh instance of the official Redmine Docker image with the REST API enabled works as well.

The tests can also manage such a local instance themselves. If REDMINE_TEST_CONTAINER_RUNTIME is set to podman or docker the tests make sure a container with the official Redmine image for REDMINE_VERSION (and a PostgreSQL container for its database) is running before they start, creating or starting the containers if necessary. Redmine is published on the port from REDMINE_URL (which has to be a URL like http://127.0.0.1:3100) and the admin user gets the API key from REDMINE_API_KEY (e.g. 40 random hex digits). The containers are named redmine-api-test-<version> and redmine-api-test-<version>-db and are left running for the next test run, remove both to start over with an empty database.

§Tested Redmine versions

On 2026-11-18 the full test suite was run against every Redmine version from 7.0.3 down to 4.2.10 that is available as an official Redmine Docker image:

  • 5.0.0 to 7.0.3 work, except for 6.0.0 and 6.0.1
  • 6.0.1 returns the hours of time entries as a fraction (e.g. “1/1”) instead of a number which can not be parsed, this is Redmine bug #41819, fixed in 6.0.2. 6.0.0 has no Docker image but has the same code so it is affected as well. Everything else works with those versions.
  • 4.2.10 and older are not supported, listing trackers fails because the enabled_standard_fields of trackers were only added in Redmine 5.0

Fields added in later Redmine versions are optional in the corresponding types (e.g. the description of issue statuses, added in Redmine 5.1).

§How to use this crate

All the examples in this README file assume that REDMINE_API_KEY and REDMINE_URL are set in either the environment or a .env file (if you do not use the .env file you can skip the dotenv line).

There are five main ways to call API endpoints:

  • ignoring the response body
  • returning the JSON response body
  • returning a single page from a query that supports pagination
  • returning all pages from a query that supports pagination
  • using an Iterator (for the sync API) or a Stream (for the async API)

All the examples below use the blocking Api but it is also possible to use the async API merely by creating a reqwest::Client instead of a reqwest::blocking::Client and using RedmineAsync instead of Redmine (and of course adding .await where appropriate). They do use the re-exported version of reqwest to avoid version conflicts if the user has another version of the reqwest crate in their dependency graph.

§The Endpoint trait

Each API endpoint is represented by an object implementing the Endpoint trait.

Each of them has a Builder to set any potential parameters. For uniformity this pattern is used even when there are no parameters.

The vast majority of endpoints are in a module under api that matches the Redmine wiki page that documents the API endpoint.

The exception is the FileUpload endpoint and tests related to that which lives in api::uploads.

The endpoint is the generic parameter we do not explicitly specify in the calls below.

§Wrapper types

A lot of API responses return the actual response wrapped in or require the request to be wrapped in an extra JSON object with one key named after singular or plural of the entity the call handles. I have provided generic Wrapper types, e.g. IssueWrapper to allow the user of this crate to discard them as soon as possible.

I decided against completely hiding them away behind the API for non-pagination queries since that might have given the user less flexibility.

§Using your own return types

Instead of the supplied return types it is possible to use your own types or even something like serde_json::Value. This allows you to extract the fields you need directly into your own types, e.g. just the Id.

§Essentials types

In the API responses we often find lists of other entities in a minimal form, e.g. just the id and name. I have named these types after the main entity followed by Essentials, e.g. IssueEssentials.

§Ignoring the response body

This is mainly useful in practice for queries that do not have a response body (e.g. delete queries) or for queries that have a side-effect (like creating an issue) where we do not care about the response body.

For illustrative purposes I am using the GetUser endpoint (fetching the current user) here mainly to avoid accidental data loss from running a delete example copied from here on a production Redmine instance.

use redmine_api::api::users::GetUser;
use redmine_api::api::Redmine;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv()?;
    let client = redmine_api::reqwest::blocking::Client::builder()
        .use_rustls_tls()
        .build()?;
    let redmine = Redmine::from_env(client)?;
    let endpoint = GetUser::builder().build()?;
    redmine.ignore_response_body::<_>(&endpoint)?;
    Ok(())
}

§Returning a JSON response

This is used for most of the API endpoints, it requires the endpoint to implement the ReturnsJsonResponse trait so it can not be accidentally used on an endpoint which always returns an empty response body.

If this is used on an endpoint that requires pagination a compile time error will be emitted to avoid accidentally writing code that ignores all but the first page. This is implemented by having all endpoints that do not implement pagination implement the NoPagination trait.

use redmine_api::api::users::{GetUser, User, UserWrapper};
use redmine_api::api::Redmine;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv()?;
    let client = redmine_api::reqwest::blocking::Client::builder()
        .use_rustls_tls()
        .build()?;
    let redmine = Redmine::from_env(client)?;
    let endpoint = GetUser::builder().build()?;
    let UserWrapper { user } = redmine.json_response_body::<_, UserWrapper<User>>(&endpoint)?;
    println!("Current user:\n{:#?}", user);
    Ok(())
}

§Pagination (single page)

This is used for a few API endpoints that can return large numbers of results.

It requires the endpoint to implement the Pageable trait so it can not accidentally be used on endpoints which do not support pagination.

Since pagination queries always have an outer wrapper object which contain the pagination keys (total_count, offset, limit) which have to be parsed anyway the explicit use of a Wrapper object is not required on pagination queries.

However the call does require the offset and limit parameters and the response is wrapped in the ResponsePage struct to return these values.

use redmine_api::api::issues::{Issue, ListIssues};
use redmine_api::api::{Redmine, ResponsePage};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv()?;
    let client = redmine_api::reqwest::blocking::Client::builder()
        .use_rustls_tls()
        .build()?;
    let redmine = Redmine::from_env(client)?;
    let endpoint = ListIssues::builder().build()?;
    let ResponsePage {
        values: issues,
        total_count,
        offset,
        limit,
    } = redmine.json_response_body_page::<_, Issue>(&endpoint, 3, 25)?;
    println!("Total count: {}", total_count);
    println!("Offset: {}", offset);
    println!("Limit: {}", limit);
    for issue in issues {
        println!("Issue found:\n{:#?}", issue);
    }
    Ok(())
}

§Pagination (all pages)

Most of the things said in the previous section also apply here.

Since we request all pages we do not require an offset or limit parameter nor are the results wrapped in an extra object.

The downside of this is that it needs to accumulate all results in memory before returning them so it is more meant to be used with something like projects or groups where common numbers of results might just be over one page and not so much for those where hundreds of result pages are expected like unfiltered issues.

use redmine_api::api::issues::{Issue, ListIssues};
use redmine_api::api::Redmine;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv()?;
    let client = redmine_api::reqwest::blocking::Client::builder()
        .use_rustls_tls()
        .build()?;
    let redmine = Redmine::from_env(client)?;
    let endpoint = ListIssues::builder().build()?;
    let issues = redmine.json_response_body_all_pages::<_, Issue>(&endpoint)?;
    for issue in issues {
        println!("Issue found:\n{:#?}", issue);
    }
    Ok(())
}

§Iterator

This is available on endpoints that require pagination as it is obviously useless if no results are returned and the result from a single call can easily be turned into an Iterator as seen in our loop above.

The main advantage over the all pages version is that the results can be streamed instead of having to keep them all in memory at the same time.

This means the main advantage is for e.g. getting all the issues in a redmine instance, not for entities like projects where the number of pages are in the low single digits on most instances.

use redmine_api::api::issues::{Issue, ListIssues};
use redmine_api::api::Redmine;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenvy::dotenv()?;
    let client = redmine_api::reqwest::blocking::Client::builder()
        .use_rustls_tls()
        .build()?;
    let redmine = Redmine::from_env(client)?;
    let endpoint = ListIssues::builder().build()?;
    let issues = redmine.json_response_body_all_pages_iter::<_, Issue>(&endpoint);
    for issue in issues {
        let issue = issue?;
        println!("Issue found:\n{:#?}", issue);
    }
    Ok(())
}

Re-exports§

pub use reqwest;

Modules§

api
Redmine API

Enums§

Error
Error type for redmine_api