Package javiergs.tulip.taiga

Class TaigaClient

java.lang.Object
javiergs.tulip.taiga.TaigaClient
public class TaigaClient extends Object
Taiga REST API client.

This client supports authentication and a focused set of CRUD operations for projects, sprints (milestones), user stories, tasks, users, and task statuses.

Typical usage:

  1. Create a client instance with a Taiga host URL.
  2. Call login(String, String) once to obtain a bearer token.
  3. Call read/write methods (for example getMyProjects() or createTask(long, Long, String, Long)).

All authenticated operations require a successful login first; otherwise an IllegalStateException is thrown.

HTTP non-2xx responses are surfaced as runtime failures with response details. Methods that perform I/O declare checked exceptions from Java HTTP and JSON processing APIs.

Thread-safety: instances are not designed for concurrent mutable use because the authentication token is stored as mutable state.

Version:
2026.05.27

  • Constructor Details

    • TaigaClient

      public TaigaClient(String host)
      Creates a new Taiga API client.
      Parameters:
      host - base Taiga API host, for example https://api.taiga.io

  • Method Details

    • login

      public void login(String username, String password) throws Exception
      Authenticates the client using Taiga username/password credentials.
      Parameters:
      username - Taiga username
      password - Taiga password
      Throws:
      Exception - if authentication fails or the API does not return an auth token

    • getMyProjects

      public List<TaigaProject> getMyProjects() throws Exception
      Retrieves all projects accessible to the authenticated user.
      Returns:
      list of accessible Taiga projects
      Throws:
      Exception - if the user is not authenticated or the API request fails

    • getProject

      public TaigaProject getProject(long projectId) throws IOException, InterruptedException
      Retrieves a project by id.
      Parameters:
      projectId - Taiga project id
      Returns:
      project information
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • getSprints

      public List<TaigaSprint> getSprints(long projectId) throws Exception
      Retrieves all sprints/milestones for a project.
      Parameters:
      projectId - Taiga project id
      Returns:
      list of sprints/milestones in the project
      Throws:
      Exception - if the user is not authenticated or the API request fails

    • getSprint

      public TaigaSprint getSprint(long sprintId) throws IOException, InterruptedException
      Retrieves a sprint/milestone by id.
      Parameters:
      sprintId - Taiga sprint/milestone id
      Returns:
      sprint information
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • getStories

      public List<TaigaUserStory> getStories(long projectId) throws Exception
      Retrieves all user stories for a project.
      Parameters:
      projectId - Taiga project id
      Returns:
      list of user stories in the project
      Throws:
      Exception - if the user is not authenticated or the API request fails

    • getStory

      public TaigaUserStory getStory(long storyId) throws IOException, InterruptedException
      Retrieves a user story by id.
      Parameters:
      storyId - Taiga user story id
      Returns:
      user story information
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • getStoriesBySprint

      public List<TaigaUserStory> getStoriesBySprint(long sprintId) throws Exception
      Retrieves all user stories assigned to a sprint/milestone.
      Parameters:
      sprintId - Taiga sprint/milestone id
      Returns:
      list of user stories assigned to the sprint
      Throws:
      Exception - if the user is not authenticated or the API request fails

    • getTasks

      public List<TaigaTask> getTasks(long projectId) throws Exception
      Retrieves all tasks for a project.
      Parameters:
      projectId - Taiga project id
      Returns:
      list of tasks in the project
      Throws:
      Exception - if the user is not authenticated or the API request fails

    • getTask

      public TaigaTask getTask(long taskId) throws IOException, InterruptedException
      Retrieves a task by id.
      Parameters:
      taskId - Taiga task id
      Returns:
      task information
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • getUserById

      public TaigaUser getUserById(long userId) throws Exception
      Retrieves a Taiga user by id.
      Parameters:
      userId - Taiga user id
      Returns:
      user information
      Throws:
      Exception - if the user is not authenticated or the API request fails

    • getTaskStatuses

      public List<TaigaStatus> getTaskStatuses(long projectId) throws Exception
      Retrieves the available task statuses for a project.
      Parameters:
      projectId - Taiga project id
      Returns:
      list of task statuses configured for the project
      Throws:
      Exception - if the user is not authenticated or the API request fails

    • getTaskStatusMap

      public Map<Long,String> getTaskStatusMap(long projectId) throws Exception
      Retrieves task statuses as a map from status id to status name.
      Parameters:
      projectId - Taiga project id
      Returns:
      map where keys are status ids and values are status names
      Throws:
      Exception - if the user is not authenticated or the API request fails

    • createProject

      public TaigaProject createProject(String name, String description) throws IOException, InterruptedException
      Creates a new Taiga project.
      Parameters:
      name - project name
      description - project description; if null, an empty description is used
      Returns:
      created project
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • createSprint

      public TaigaSprint createSprint(long projectId, String name, String estimatedStart, String estimatedFinish) throws IOException, InterruptedException
      Creates a new sprint/milestone in a project.
      Parameters:
      projectId - Taiga project id
      name - sprint name
      estimatedStart - estimated start date in yyyy-MM-dd format
      estimatedFinish - estimated finish date in yyyy-MM-dd format
      Returns:
      created sprint/milestone
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • createUserStory

      public TaigaUserStory createUserStory(long projectId, String subject, String description, Long milestoneId) throws IOException, InterruptedException
      Creates a new user story in a project.
      Parameters:
      projectId - Taiga project id
      subject - story subject/title
      description - story description; if null, an empty description is used
      milestoneId - optional sprint/milestone id; may be null
      Returns:
      created user story
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • createTask

      public TaigaTask createTask(long projectId, Long userStoryId, String subject, Long assignedToUserId) throws IOException, InterruptedException
      Creates a new task in a project.
      Parameters:
      projectId - Taiga project id
      userStoryId - optional parent user story id; may be null
      subject - task subject/title
      assignedToUserId - optional assigned user id; may be null
      Returns:
      created task
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • moveStoryToSprint

      public TaigaUserStory moveStoryToSprint(long storyId, Long sprintId) throws IOException, InterruptedException
      Moves a user story to another sprint/milestone.
      Parameters:
      storyId - Taiga user story id
      sprintId - destination sprint/milestone id; use null to remove from sprint
      Returns:
      updated user story
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • assignTaskToStory

      public TaigaTask assignTaskToStory(long taskId, Long userStoryId) throws IOException, InterruptedException
      Assigns a task to a user story, or removes the current user-story association.
      Parameters:
      taskId - Taiga task id
      userStoryId - destination user story id; use null to detach the task
      Returns:
      updated task
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • deleteTask

      public void deleteTask(long taskId) throws IOException, InterruptedException
      Deletes a task.
      Parameters:
      taskId - Taiga task id
      Throws:
      IOException - if the HTTP request fails
      InterruptedException - if the request is interrupted

    • deleteUserStory

      public void deleteUserStory(long storyId) throws IOException, InterruptedException
      Deletes a user story.
      Parameters:
      storyId - Taiga user story id
      Throws:
      IOException - if the HTTP request fails
      InterruptedException - if the request is interrupted

    • deleteSprint

      public void deleteSprint(long sprintId) throws IOException, InterruptedException
      Deletes a sprint/milestone.
      Parameters:
      sprintId - Taiga sprint/milestone id
      Throws:
      IOException - if the HTTP request fails
      InterruptedException - if the request is interrupted

    • deleteProject

      public void deleteProject(long projectId) throws IOException, InterruptedException
      Deletes a project.
      Parameters:
      projectId - Taiga project id
      Throws:
      IOException - if the HTTP request fails
      InterruptedException - if the request is interrupted

    • updateProject

      public TaigaProject updateProject(long projectId, String name, String description) throws IOException, InterruptedException
      Updates a project.
      Parameters:
      projectId - Taiga project id
      name - new project name; if null, the name is not changed
      description - new project description; if null, the description is not changed
      Returns:
      updated project
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • updateSprint

      public TaigaSprint updateSprint(long sprintId, String name, String estimatedStart, String estimatedFinish) throws IOException, InterruptedException
      Updates a sprint/milestone.
      Parameters:
      sprintId - Taiga sprint/milestone id
      name - new sprint name; if null, the name is not changed
      estimatedStart - new estimated start date in yyyy-MM-dd format; if null, it is not changed
      estimatedFinish - new estimated finish date in yyyy-MM-dd format; if null, it is not changed
      Returns:
      updated sprint/milestone
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • updateUserStory

      public TaigaUserStory updateUserStory(long storyId, String subject, String description, Long milestoneId) throws IOException, InterruptedException
      Updates a user story.

      The current user story version is retrieved automatically and included in the PATCH request.

      Parameters:
      storyId - Taiga user story id
      subject - new story subject/title; if null, the subject is not changed
      description - new story description; if null, the description is not changed
      milestoneId - new sprint/milestone id; if null, the milestone is not changed
      Returns:
      updated user story
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • updateTask

      public TaigaTask updateTask(long taskId, String subject, Long assignedToUserId, Long userStoryId) throws IOException, InterruptedException
      Updates a task.

      The current task version is retrieved automatically and included in the PATCH request.

      Parameters:
      taskId - Taiga task id
      subject - new task subject/title; if null, the subject is not changed
      assignedToUserId - new assigned user id; if null, assignment is not changed
      userStoryId - new parent user story id; if null, parent story is not changed
      Returns:
      updated task
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted

    • moveTaskToStatus

      public TaigaTask moveTaskToStatus(long taskId, long statusId) throws IOException, InterruptedException
      Moves a task to another status.

      The current task version is retrieved automatically and included in the PATCH request.

      Parameters:
      taskId - Taiga task id
      statusId - destination task status id
      Returns:
      updated task
      Throws:
      IOException - if the HTTP request or JSON parsing fails
      InterruptedException - if the request is interrupted