Bitbucket REST v2 migration for app developers

This document will guide you through the migration of your Marketplace app from REST v1 to REST v2. Bitbucket Data Center has migrated to REST v2 as part of the upgrade to Platform 7.

These documents include Atlassian REST v2 migration guides:

• Prepare your app for Platform 7
• Atlassian REST upgrade

The rest of this documentation will be Bitbucket specific REST v2 migration.

Update plugin pom to use the correct dependencies

Bitbucket REST package replacements

Plugin resource updates

Inject custom resolvers

Update @Context with @BeanParams for injecting custom resolvers constructed from request parameters into a resource. Then, use the custom resolvers to get the appropriate object.

1
2
// REST v1
public Response getProjectData(@Context Project project) {
    ...
}
// REST v2
public Response getProjectData(@BeanParam ProjectResolver projectResolver) {
    Project project = projectResolver.getProject();
    ...
}

The custom resolvers that we currently support may require additional OSGi imports:

RestUtils properties and methods migration

com.atlassian.bitbucket.rest.util.RestUtils was separated into helper classes as below:

ExceptionMapper changes

com.atlassian.bitbucket.rest.exception.UnhandledExceptionMapper was removed in REST v2. All the standard Bitbucket exceptions will be mapped to the appropriate status code by the Bitbucket application.

• For custom exception handling, implement the javax.ws.rs.ext.ExceptionMapper and override the toResponse method.
• Annotate the custom exception mapper with @Provider for runtime discovery.

1
2
@Provider
@Singleton
public class CustomExceptionMapper implements ExceptionMapper<CustomException> {
    @Override
    public Response toResponse(CustomException exception) {
            return ResponseFactory.status(Response.Status.FORBIDDEN)
                    .entity(new RestErrors(exception.getLocalizedMessage()))
                    .build();
    }
}

Removed APIs

@com.atlassian.bitbucket.rest.annotation.SecondaryRepository annotation was removed in REST v2.

com.atlassian.bitbucket.rest.util.StreamingResponse was removed in REST v2.

com.atlassian.bitbucket.rest.RestResource was removed in REST v2. Resources relying on RestResource previously must now throw their own exceptions directly.

RestFragment changes

RestFragments have migrated from bitbucket-rest-spi to bitbucket-rest-v2-spi.

The imports have changed from com.atlassian.bitbucket.rest.fragment.* to com.atlassian.bitbucket.rest.v2.fragment.*.

Its configuration remains the same, more information available on REST fragment plugin module