Package org.sourcelab.buildkite.api.client

Class BuildkiteClient

java.lang.Object

org.sourcelab.buildkite.api.client.BuildkiteClient

public class BuildkiteClient
extends Object

API Client for Buildkite's REST Api. See API Documentation:

Constructor Summary

Constructors

Constructor	Description
BuildkiteClient(Configuration configuration)	Constructor.

Method Summary

Modifier and Type	Method	Description
Build	cancelBuild(String organizationSlugId, String pipelineSlugId, long buildNumber)	Cancels the build if its state is either scheduled or running.
Build	createBuild(CreateBuildOptions createBuildOptions)	Creates a new build to be executed.
Build	createBuild(CreateBuildOptionsBuilder createBuildOptions)	Creates a new build to be executed.
boolean	deleteAccessToken()	Deletes/Revokes the current AccessToken.
<T> T	executeRequest(Request<T> request)	Execute the given request, returning the parsed response, or throwing the appropriate exception if an error was returned from the API.
<T> T	firstPage(PageableResponse<T> response)	Retrieve the first page of results from the previously retrieved request.
AccessTokenResponse	getAccessToken()	Retrieve details about the current AccessToken.
Optional<Build>	getBuild(String organizationSlugId, String pipelineSlugId, long buildNumber)	Retrieve a specific build based on the filter criteria.
Optional<Build>	getBuild(GetBuildFilters filters)	Retrieve a specific build based on the filter criteria.
Optional<Build>	getBuild(GetBuildFiltersBuilder filters)	Retrieve a specific build based on the filter criteria.
MetaResponse	getMeta()	Retrieves metadata endpoint.
Optional<Organization>	getOrganization(String organizationSlugId)	Retrieve specific organization via its Organization slug id.
Optional<Pipeline>	getPipeline(String organizationSlugId, String pipelineSlugId)	Retrieve specific pipeline via its Organization and Pipeline Slug Ids.
CurrentUserResponse	getUser()	Retrieves the current user associated with the current access token.
<T> T	lastPage(PageableResponse<T> response)	Retrieve the last page of results from the previously retrieved request.
ListBuildsResponse	listBuilds()	Retrieve all Builds accessible to the current user/API access token, across all Organizations.
ListBuildsResponse	listBuilds(BuildFilters filters)	Retrieve all builds which match the supplied search criteria.
ListBuildsResponse	listBuilds(BuildFiltersBuilder filtersBuilder)	Retrieve all builds which match the supplied search criteria.
List<Emoji>	listEmojis(String orgIdSlug)	List all Emojis defined in the given Organization.
ListOrganizationsResponse	listOrganizations()	Retrieve all Organizations accessible to the current user/API access token.
ListOrganizationsResponse	listOrganizations(OrganizationFilters filters)	Retrieve all Organizations accessible to the current user/API access token.
ListOrganizationsResponse	listOrganizations(OrganizationFiltersBuilder filters)	Retrieve all Organizations accessible to the current user/API access token.
ListPipelinesResponse	listPipelines(String organizationSlugId)	Retrieve all Pipelines accessible to the current user/API access token for the given Organization.
ListPipelinesResponse	listPipelines(PipelineFilters filters)	Retrieve all Pipelines accessible to the current user/API access token for the given Organization.
ListPipelinesResponse	listPipelines(PipelineFiltersBuilder filters)	Retrieve all Pipeline accessible to the current user/API access token for the given Organization.
<T> T	nextPage(PageableResponse<T> response)	Retrieve the next page of results from the previously retrieved request.
PingResponse	ping()	Make a 'test' or 'hello world' request to the Buildkite API.
<T> T	previousPage(PageableResponse<T> response)	Retrieve the previous page of results from the previously retrieved request.
Build	rebuildBuild(String organizationSlugId, String pipelineSlugId, long buildNumber)	Retries a build.
Job	retryJob(RetryJobOptions options)	Retries a failed or timed_out job.
Job	retryJob(RetryJobOptionsBuilder options)	Retries a failed or timed_out job.
Job	unblockJob(UnblockJobOptions options)	Unblocks a build's "Block pipeline" job.
Job	unblockJob(UnblockJobOptionsBuilder options)	Unblocks a build's "Block pipeline" job.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

BuildkiteClient

public BuildkiteClient(Configuration configuration)

Constructor.

Parameters:

configuration - The configuration for the client.

Method Details

ping

public PingResponse ping()
                  throws BuildkiteException

Make a 'test' or 'hello world' request to the Buildkite API. Can be used to validate connectivity to the API.

Returns:

Response details from the ping request.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api

getAccessToken

public AccessTokenResponse getAccessToken()
                                   throws BuildkiteException

Retrieve details about the current AccessToken.

Returns:

Details about the current AccessToken.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/access-token

deleteAccessToken

public boolean deleteAccessToken()
                          throws BuildkiteException

Deletes/Revokes the current AccessToken.

Returns:

Details about the current AccessToken.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/access-token#revoke-the-current-token

getUser

public CurrentUserResponse getUser()
                            throws BuildkiteException

Retrieves the current user associated with the current access token.

Returns:

Details about the current User.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/user#get-the-current-user

listOrganizations

public ListOrganizationsResponse listOrganizations()
                                            throws BuildkiteException

Retrieve all Organizations accessible to the current user/API access token. Results will be paged.

Returns:

All Organizations accessible to the current user/API access token. Results will be paged if the number of results exceeds 30.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/organizations#list-organizations

listOrganizations

public ListOrganizationsResponse listOrganizations(OrganizationFiltersBuilder filters)
                                            throws BuildkiteException

Retrieve all Organizations accessible to the current user/API access token. Results will be paged.

Parameters:

filters - Filter criteria.

Returns:

All Organizations accessible to the current user/API access token. Results will be paged if the number of results exceeds 30.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/organizations#list-organizations

listOrganizations

public ListOrganizationsResponse listOrganizations(OrganizationFilters filters)
                                            throws BuildkiteException

Retrieve all Organizations accessible to the current user/API access token. Results will be paged.

Parameters:

filters - Filter criteria.

Returns:

All Organizations accessible to the current user/API access token. Results will be paged if the number of results exceeds 30.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/organizations#list-organizations

getOrganization

public Optional<Organization> getOrganization(String organizationSlugId)
                                       throws BuildkiteException

Retrieve specific organization via its Organization slug id.

Parameters:

organizationSlugId - Slug of the organization to retrieve.

Returns:

Organization matching the slug, if found.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/organizations#get-an-organization

listPipelines

public ListPipelinesResponse listPipelines(PipelineFiltersBuilder filters)
                                    throws BuildkiteException

Retrieve all Pipeline accessible to the current user/API access token for the given Organization. Results will be paged.

Parameters:

filters - Filter criteria.

Returns:

All Pipelines accessible to the current user/API access token. Results will be paged if the number of results exceeds 30.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/pipelines#list-pipelines

listPipelines

public ListPipelinesResponse listPipelines(PipelineFilters filters)
                                    throws BuildkiteException

Retrieve all Pipelines accessible to the current user/API access token for the given Organization. Results will be paged.

Parameters:

filters - Filter criteria.

Returns:

All Pipelines accessible to the current user/API access token. Results will be paged if the number of results exceeds 30.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/pipelines#list-pipelines

listPipelines

public ListPipelinesResponse listPipelines(String organizationSlugId)
                                    throws BuildkiteException

Retrieve all Pipelines accessible to the current user/API access token for the given Organization. Results will be paged.

Parameters:

organizationSlugId - Organization Slug Id to retrieve pipelines for.

Returns:

All Pipelines accessible to the current user/API access token for the given Organization. Results will be paged if the number of results exceeds 30.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/pipelines#list-pipelines

getPipeline

public Optional<Pipeline> getPipeline(String organizationSlugId,
 String pipelineSlugId)
                               throws BuildkiteException

Retrieve specific pipeline via its Organization and Pipeline Slug Ids.

Parameters:

organizationSlugId - Slug of the organization to retrieve.

pipelineSlugId - Slug of the pipeline to retrieve.

Returns:

Pipeline matching the slug, if found.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/pipelines#get-a-pipeline

listBuilds

public ListBuildsResponse listBuilds()

Retrieve all Builds accessible to the current user/API access token, across all Organizations. Results will be paged.

Returns:

All Builds accessible to the current user/API access token, across all Organizations. Results will be paged if the number of results exceeds 30.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/builds#list-all-builds

listBuilds

public ListBuildsResponse listBuilds(BuildFiltersBuilder filtersBuilder)

Retrieve all builds which match the supplied search criteria.

Parameters:

filtersBuilder - Filter criteria.

Returns:

All builds which match the supplied search criteria. Results will be paged if the number of results exceeds 30 (or the page limit specified in the search criteria).

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/builds#list-all-builds

listBuilds

public ListBuildsResponse listBuilds(BuildFilters filters)

Retrieve all builds which match the supplied search criteria.

Parameters:

filters - Filter criteria.

Returns:

All builds which match the supplied search criteria. Results will be paged if the number of results exceeds 30 (or the page limit specified in the search criteria).

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/builds#list-all-builds

getBuild

public Optional<Build> getBuild(GetBuildFiltersBuilder filters)

Retrieve a specific build based on the filter criteria.

Parameters:

filters - Filter criteria.

Returns:

The build which matches the criteria if found.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/builds#get-a-build

getBuild

public Optional<Build> getBuild(String organizationSlugId,
 String pipelineSlugId,
 long buildNumber)

Retrieve a specific build based on the filter criteria.

Parameters:

organizationSlugId - Organization associated with the build.

pipelineSlugId - Pipeline associated with the build.

buildNumber - The build number.

Returns:

The build which matches the criteria if found.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/builds#get-a-build

getBuild

public Optional<Build> getBuild(GetBuildFilters filters)

Retrieve a specific build based on the filter criteria.

Parameters:

filters - Filter criteria.

Returns:

The build which matches the criteria if found.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/builds#get-a-build

cancelBuild

public Build cancelBuild(String organizationSlugId,
 String pipelineSlugId,
 long buildNumber)

Cancels the build if its state is either scheduled or running.

Parameters:

organizationSlugId - Organization associated with the build.

pipelineSlugId - Pipeline associated with the build.

buildNumber - The build number.

Returns:

Updated Build instance.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/builds#cancel-a-build

createBuild

public Build createBuild(CreateBuildOptionsBuilder createBuildOptions)

Creates a new build to be executed.

Parameters:

createBuildOptions - Defines the build to be created.

Returns:

Created Build instance.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/builds#create-a-build

createBuild

public Build createBuild(CreateBuildOptions createBuildOptions)

Creates a new build to be executed.

Parameters:

createBuildOptions - Defines the build to be created.

Returns:

Created Build instance.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/builds#create-a-build

rebuildBuild

public Build rebuildBuild(String organizationSlugId,
 String pipelineSlugId,
 long buildNumber)

Retries a build.

Parameters:

organizationSlugId - Organization associated with the build.

pipelineSlugId - Pipeline associated with the build.

buildNumber - The build number.

Returns:

Updated Build instance.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/builds#rebuild-a-build

retryJob

public Job retryJob(RetryJobOptionsBuilder options)

Retries a failed or timed_out job. You can only retry each job.id once. To retry a "second time" use the new job.id returned in the first retry query.

Parameters:

options - Defines which Job to retry.

Returns:

Updated job instance.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/jobs#retry-a-job

retryJob

public Job retryJob(RetryJobOptions options)

Retries a failed or timed_out job. You can only retry each job.id once. To retry a "second time" use the new job.id returned in the first retry query.

Parameters:

options - Defines which Job to retry.

Returns:

Updated job instance.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/jobs#retry-a-job

unblockJob

public Job unblockJob(UnblockJobOptionsBuilder options)

Unblocks a build's "Block pipeline" job. The job's unblockable property indicates whether it is able to be unblocked, and the unblock_url property points to this endpoint.

Parameters:

options - Defines which Job to unblock.

Returns:

Updated job instance.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/jobs#unblock-a-job

unblockJob

public Job unblockJob(UnblockJobOptions options)

Unblocks a build's "Block pipeline" job. The job's unblockable property indicates whether it is able to be unblocked, and the unblock_url property points to this endpoint.

Parameters:

options - Defines which Job to unblock.

Returns:

Updated job instance.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/jobs#unblock-a-job

listEmojis

public List<Emoji> listEmojis(String orgIdSlug)

List all Emojis defined in the given Organization.

Parameters:

orgIdSlug - Organization Id slug to retrieve list of emojis for.

Returns:

List of Emojis.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/emojis#list-emojis

getMeta

public MetaResponse getMeta()
                     throws BuildkiteException

Retrieves metadata endpoint.

Returns:

Details about the current User.

Throws:

BuildkiteException - if API returns an error response.

See Also:

• https://buildkite.com/docs/apis/rest-api/meta#get-meta-information

nextPage

public <T> T nextPage(PageableResponse<T> response)

Retrieve the next page of results from the previously retrieved request.

Type Parameters:

T - The parsed return object representing the result.

Parameters:

response - Previously retrieved result/response to retrieve the next page of results for.

Returns:

The next page of results.

Throws:

InvalidPagingRequestException - if no next page exists to retrieve.

BuildkiteException - if API returns an error response.

previousPage

public <T> T previousPage(PageableResponse<T> response)

Retrieve the previous page of results from the previously retrieved request.

Type Parameters:

T - The parsed return object representing the result.

Parameters:

response - Previously retrieved result/response to retrieve the previous page of results for.

Returns:

The previous page of results.

Throws:

InvalidPagingRequestException - if no previous page exists to retrieve.

BuildkiteException - if API returns an error response.

firstPage

public <T> T firstPage(PageableResponse<T> response)

Retrieve the first page of results from the previously retrieved request.

Type Parameters:

T - The parsed return object representing the result.

Parameters:

response - Previously retrieved result/response to retrieve the first page of results for.

Returns:

The first page of results.

Throws:

InvalidPagingRequestException - if no previous page exists to retrieve.

BuildkiteException - if API returns an error response.

lastPage

public <T> T lastPage(PageableResponse<T> response)

Retrieve the last page of results from the previously retrieved request.

Type Parameters:

T - The parsed return object representing the result.

Parameters:

response - Previously retrieved result/response to retrieve the last page of results for.

Returns:

The last page of results.

Throws:

InvalidPagingRequestException - if no previous page exists to retrieve.

BuildkiteException - if API returns an error response.

executeRequest

public <T> T executeRequest(Request<T> request)
                     throws BuildkiteException

Execute the given request, returning the parsed response, or throwing the appropriate exception if an error was returned from the API. This method scoped public to allow for user defined requests to be executed by the library as an extension point.

Type Parameters:

T - The parsed response object.

Parameters:

request - The request to execute.

Returns:

The parsed response object.

Throws:

BuildkiteException - if API returns an error response.