llorllale / youtrack-api

Fluent, object-oriented Java wrapper for YouTrack's REST API.

youtrack-api

youtrack-api is a fluent, object-oriented Java API for YouTrack. Visit the project's site for more info.

Here's a snippet of its usage:

final YouTrack youtrack = new DefaultYouTrack(
    new PermanentToken(new URL("http://youtrack"), "your_token")
);
final User leader = youtrack.users()        //Users API under construction - see #246
  .filter(u -> u.loginName().equals("mike"))
  .findFirst().get();
youtrack.projects()
    .create("TP", "Test Project", leader)   //creates project
    .issues()
    .create("summary", "description")       //creates issue
    .comments()
    .post("Hello World!");                  //posts comment to the issue

Dependencies

• Java 8+.
• Apache's HttpClient version 4.5.x.
• Apache's HttpClient HttpMime version 4.5.x.

Feedback

Please direct any questions, feature requests or bugs to the issue tracker.

How do I contribute?

Please view our guidelines for contributing here.

License

youtrack-api is licensed under the Apache License, Version 2.0. A copy of the license has been included in LICENSE.

Icon made by Freepik from www.flaticon.com is licensed by CC BY 3.0

youtrack-api's Issues

Issue priority

• Retrieve all possible issue priorities
• Update an issue's priority

Generic search for Issues

Refs:

• https://www.jetbrains.com/help/youtrack/standalone/Get-the-List-of-Issues.html
• https://www.jetbrains.com/help/youtrack/standalone/Search-for-Issues.html

IssueSpec.equals()

Implement IssueSpec.equals(Object) method.

Various documentation issues

• The snippet included in the site index page directly creates an instance of YouTrack (the interface) as opposed to DefaultYouTrack
• Expand usage.md

Update index.md with changes introduced in #32

Get Comments of an Issue

Javadoc for IssueSpec

The scope for IssueSpec is not clear in its javadoc. What fields does it include? What fields does it not include? Why not?

Remove a Comment for an Issue

Ref: https://www.jetbrains.com/help/youtrack/standalone/Remove-a-Comment-for-an-Issue.html

Hide util and util.response packages

Related to #91

Merge packages org.llorllale.youtrack.api.util and org.llorllale.youtrack.api.util.response into org.llorllale.youtrack.api and give all those classes/interfaces package access so that they are not reachable by users.

More rigorous checkstyle rules

To maintain code quality we need more rigorous checkstyle rules - moreso than Google's.

Use something like this: https://github.com/llorllale/netbeans-youtrack-issues-plugin/blob/master/checkstyle.xml

Javadoc in project site including unwanted packages

Packages that should be left out of javadocs:

• org.llorllale.youtrack.api.jaxb
• org.llorllale.youtrack.api.util
• org.llorllale.youtrack.api.util.response

The javadocs deployed to maven central don't have this issue.

Update a Comment

Issue types

• Retrieve all possible issue types
• Update an issue's type

Create issues for a project

Model issue

The following attributes of Issue are not always present in a YouTrack project:

• State
• Type
• Priority
• TimeTracking (?) - it can be disabled per project

These are all custom fields for projects in YouTrack, so what we should really have is a Project.fields() property that will list all assignable fields in a project, whereas in Issue we would have Issue.fields() which would list all fields that have been assigned to this issue.

Issue.spec()

Implement Issue.spec() to expose an issue as a spec. This will make it easier to check for any changes that a user desires to perform on an issue in an issue tracker.

Fix project README

Fix the project's README by adding:

• Short project description and a link to the project's site
• Badges:
  • CodeCov
  • Travis CI
  • Maven Central

UsernamePasswordLoginTest.authenticationError() failure

Failure message: java.lang.AssertionError: Expected exception: org.llorllale.youtrack.api.session.AuthenticationException

Root cause: implementation is not validating server response status.

API sucks - needs big improvement

See:

• https://github.com/jcabi/jcabi-github
• http://www.yegor256.com/2017/09/12/evil-object-name-suffix-client.html

travis.yml: error setting $VERSION

Introduced in #76.

The build job is adding all the maven "Download..." output to the value of VERSION. That is likely why this build step later fails with [ERROR] No plugin found for prefix 'https'.

Search for issue by a given ID

Change 'all' method calls to return streams and not a collection

This would remove an unnecessary step.

Take for example the snippet provided in the about page:

//creating an issue
youtrack.projects()
    .all()                                    //list all projects
    .stream()
    .filter(p -> p.id().equals("project_id"))
    .get()
    .issues()
    .create(new IssueSpec("summary", "type")) //create issue for the selected project
    .comments()
    .post("This is my first comment!");       //posts a comment to the newly created issue

That extra all() in there seems redundant. We can easily change this to:

//creating an issue
youtrack.projects()
    .stream()                     //stream of all projects
    .filter(p -> p.id().equals("project_id"))
    .get()
    .issues()
    .create(new IssueSpec("summary", "type")) //create issue for the selected project
    .comments()
    .post("This is my first comment!");       //posts a comment to the newly created issue

Users can very easily reduce the stream to a list with Collectors.toList().

TimeTrackEntry work types

• Retrieve all possible work types

Delete attachment from an issue

Ref: https://www.jetbrains.com/help/youtrack/standalone/Delete-Attachment-from-an-Issue.html

IssueSpec with custom fields

Enhance Issues.IssueSpec and Issues.update to include project's custom fields so that user is able to create an issue with more than just a summary and a description.

Remove unnecessary dependencies

Remove unnecessary dependencies in order to minimize "dependency hell" for users.

Some notes:

• Easy pickings: commons-lang3, java-xmlbuilder
• Not so easy pickings: guava (need to research alternatives for properly escaping URL fragments)
• Very hard: HttpClient (both production code and tests heavily depend on this)

Here is a screenshot of our current dependency graph:

Get all attachments for an Issue

Ref: https://www.jetbrains.com/help/youtrack/standalone/Get-Attachments-of-an-Issue.html

Create comments on issues

Issue states

• Retrieve all possible issue states
• Update an issue's state

Enter timetracking on issues

1241 errors in checkstyle report

The checkstyle report included in the project's site currently enumerates 1241 errors.

Please review them and fix.

Fix broken site layout

Site layout is broken with HTTPS:

• Cannot disable HTTPS
• A few links from the reflow skin are hardcoded to HTTP

Get assignees of a Project

Their logins are already present in the project XML retrieved from YouTrack.

This will be useful for UsersOfIssue#assignTo(User).

Project logo

Find a suitable logo for the project and include both in the README and in the project's site.

Hide classes not intended for public use

The problem is that as a user of this library, when I wish to eg. import Issue with my IDE I get two results - org.llorllale.youtrack.api.Issue and org.llorllale.youtrack.api.jaxb.Isssue - which is confusing.

Build enhancements

• (NEW) include continuous delivery to maven central
• (NEW) Generate changelog
• (NEW) Custom github project releases (include changelog)
• (FIX) the site generation is not creating cobertura reports for integration tests

Continuous deployment of SNAPSHOTs

Deploy SNAPSHOTs to maven central. That way users will have the latest fixes/bugs from candidate releases readily available for use.

Ship mock classes from test packages alongside production code

This is useful for users of the library who are implementing tests on their side.

Currently, without our mock classes, they would have to duplicate all that effort in their test packages.

Users for issue

For a given issue, get these users:

• assignee
• reporter
• updater

For each user, provide their name and email.

Also, implement ability to assign an issue.

Refs:

• https://www.jetbrains.com/help/youtrack/standalone/Get-an-Issue.html
• https://www.jetbrains.com/help/youtrack/standalone/Get-User-by-Login-Name.html

GET Project by its ID

Implement 'Permanent Tokens' login

Attach a file to an issue

Ref: https://www.jetbrains.com/help/youtrack/standalone/Attach-File-to-an-Issue.html

Update an Issue's summary and description

Login to a YouTrack service using a basic username/password strategy

Incorrect handling of session cookies

• Cookies are being sent with the Set-Cookie header name instead of Cookie
• The whole cookie is being returned to YouTrack, as opposed to just its value and discarding the options
• The cookies are not being coallesced into a single Cookie header

Reference: https://www.nczonline.net/blog/2009/05/05/http-cookies-explained/

Broken links in project site

Broken links:

• GitHub
• Releases
• Issue Tracking
• FindBugs Report

Travis Build failure

There is an error when trying to build the docker image for youtrack:

`[INFO] DOCKER> Pulling from library/java

[INFO] DOCKER> Digest: sha256:b91008e234402fc87e7889d6af1f36b6ece844c05989236d83d1f658a6f329b0

[INFO] DOCKER> Status: Downloaded newer image for java:8-jre

[INFO] DOCKER> Pulled java:8-jre in 9 seconds

[INFO] Building tar: /home/travis/build/llorllale/youtrack-api/target/docker/youtrack-api-test-0.1.0/tmp/docker-build.tar

[INFO] DOCKER> [youtrack-api-test-0.1.0:latest] "youtrack-api-integration-test": Created docker-build.tar in 92 milliseconds

[ERROR] DOCKER> Unable to build image [youtrack-api-test-0.1.0] : lstat youtrack/backup: no such file or directory [lstat youtrack/backup: no such file or directory ]

[INFO] ------------------------------------------------------------------------

[INFO] BUILD FAILURE

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 33.395 s

[INFO] Finished at: 2017-08-10T18:37:21+00:00

[INFO] Final Memory: 34M/274M

[INFO] ------------------------------------------------------------------------

[ERROR] Failed to execute goal io.fabric8:docker-maven-plugin:0.21.0:build (youtrack-build) on project youtrack-api: Unable to build image [youtrack-api-test-0.1.0] : lstat youtrack/backup: no such file or directory -> [Help 1]`

Missing package-info.java for `org.llorllale.youtrack.api`

Add guidelines for contributing to the project

Add a CONTRIBUTING.md file to the root of the project.

Issue estimates

• Get an issue's estimation
• Get an issue's spent time
• Set an issue's estimation