javastrava.service.ActivityService Maven / Gradle / Ivy
Show all versions of javastrava-api Show documentation
package javastrava.service;
import java.time.LocalDateTime;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import javastrava.model.StravaActivity;
import javastrava.model.StravaActivityUpdate;
import javastrava.model.StravaActivityZone;
import javastrava.model.StravaAthlete;
import javastrava.model.StravaComment;
import javastrava.model.StravaLap;
import javastrava.model.StravaPhoto;
import javastrava.service.exception.BadRequestException;
import javastrava.service.exception.NotFoundException;
import javastrava.util.Paging;
/**
* StravaActivity related services
*
* @see http://strava.github.io/api/v3/activities/
* @author Dan Shannon
*
*/
public interface ActivityService extends StravaService {
/**
*
* Create a comment on an activity.
*
*
*
* Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.
*
*
*
* Comment posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The comment will be made by the user associated with the access_token.
*
*
*
* URL POST https://www.strava.com/api/v3/activities/:id/comments
*
*
* @param activityId
* Activity identifier
* @param text
* Comment text
* @return The comment as created on Strava
* @throws NotFoundException
* if the activity does not exist
* @throws BadRequestException
* if the comment is invalid
*/
public StravaComment createComment(final Long activityId, final String text) throws NotFoundException, BadRequestException;
/**
*
* Create a comment on an activity.
*
*
*
* Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.
*
*
*
* Comment posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The comment will be made by the user associated with the access_token.
*
*
*
* URL POST https://www.strava.com/api/v3/activities/:id/comments
*
*
* @param comment
* Comment to be created
* @return The comment as created on Strava
* @throws NotFoundException
* if the activity does not exist
* @throws BadRequestException
* if the comment is invalid
*/
public StravaComment createComment(final StravaComment comment) throws NotFoundException, BadRequestException;
/**
*
* Create a comment on an activity.
*
*
*
* Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.
*
*
*
* Comment posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The comment will be made by the user associated with the access_token.
*
*
*
* URL POST https://www.strava.com/api/v3/activities/:id/comments
*
*
* @param activityId
* Activity identifier
* @param text
* Comment text
* @return (A {@link CompletableFuture} which returns) The comment as created on Strava
* @throws NotFoundException
* if the activity does not exist
* @throws BadRequestException
* if the comment is invalid
*/
public CompletableFuture createCommentAsync(final Long activityId, final String text) throws NotFoundException, BadRequestException;
/**
*
* This API endpoint is for creating manually entered {@link StravaActivity activities}. To upload a FIT, TCX or GPX file see the Upload Documentation.
*
*
*
* Requires write permissions, as requested during the authorization process.
*
*
*
* Only updates name, activity type, startDateLocal, elapsedTime, description and distance.
*
*
*
* If any other activity attributes are passed to the API, they are ignored when creating the activity.
*
*
*
* If successful, returns a 201 status code along with a detailed representation of the created activity.
*
*
*
* URL POST https://www.strava.com/api/v3/activities
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activity
* The {@link StravaActivity activity} to be uploaded
* @return The activity as it was uploaded on Strava
*/
public StravaActivity createManualActivity(final StravaActivity activity);
/**
*
* This API endpoint is for creating manually entered {@link StravaActivity activities}. To upload a FIT, TCX or GPX file see the Upload Documentation.
*
*
*
* Requires write permissions, as requested during the authorization process.
*
*
*
* Only updates name, activity type, startDateLocal, elapsedTime, description and distance.
*
*
*
* If any other activity attributes are passed to the API, they are ignored when creating the activity.
*
*
*
* If successful, returns a 201 status code along with a detailed representation of the created activity.
*
*
*
* URL POST https://www.strava.com/api/v3/activities
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activity
* The {@link StravaActivity activity} to be uploaded
* @return (A {@link CompletableFuture} which returns) The activity as it was uploaded on Strava
*/
public CompletableFuture createManualActivityAsync(final StravaActivity activity);
/**
*
* Deletes the identified {@link StravaActivity}
*
*
*
* Activity deletion can be enabled on a per application basis, email developers -at- strava.com for more information. It also requires write permissions, as requested during the authorization
* process.
*
*
*
* Returns null if the activity does not exist on Strava
*
*
*
* URL DELETE https://www.strava.com/api/v3/activities/:id
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The id of the {@link StravaActivity} to be deleted.
*
* @return Should return null
* @throws NotFoundException
* If the activity does not exist
*/
public StravaActivity deleteActivity(final Long activityId) throws NotFoundException;
/**
*
* Deletes the identified {@link StravaActivity}
*
*
*
* Activity deletion can be enabled on a per application basis, email developers -at- strava.com for more information. It also requires write permissions, as requested during the authorization
* process.
*
*
*
* Returns null if the activity does not exist on Strava
*
*
*
* URL DELETE https://www.strava.com/api/v3/activities/:id
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activity
* The {@link StravaActivity} to be deleted.
*
* @return Should return null
* @throws NotFoundException
* If the activity does not exist
*/
public StravaActivity deleteActivity(final StravaActivity activity) throws NotFoundException;
/**
*
* Deletes the identified {@link StravaActivity}
*
*
*
* Activity deletion can be enabled on a per application basis, email developers -at- strava.com for more information. It also requires write permissions, as requested during the authorization
* process.
*
*
*
* Returns null if the activity does not exist on Strava
*
*
*
* URL DELETE https://www.strava.com/api/v3/activities/:id
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The id of the {@link StravaActivity} to be deleted.
*
* @return (A {@link CompletableFuture} which returns) Should return null
* @throws NotFoundException
* If the activity does not exist
*/
public CompletableFuture deleteActivityAsync(final Long activityId) throws NotFoundException;
/**
*
* Delete a comment belonging to the authenticated user
*
*
* @param commentId
* Identifier of the comment to be deleted
* @param activityId
* Identifier of the activity the comment was posted to
* @throws NotFoundException
* if the activity or the comment does exist
*/
public void deleteComment(final Long activityId, final Integer commentId) throws NotFoundException;
/**
*
* Delete a comment belonging to the authenticated user
*
*
* @param comment
* The comment to be deleted
* @throws NotFoundException
* If the comment does not exist on Strava
*/
public void deleteComment(final StravaComment comment) throws NotFoundException;
/**
*
* Delete a comment belonging to the authenticated user
*
*
* @param commentId
* Identifier of the comment to be deleted
* @param activityId
* Identifier of the activity the comment was posted to
* @return A {@link CompletableFuture} which indicates when the deletion is complete
* @throws NotFoundException
* if the activity or the comment does exist
*/
public CompletableFuture deleteCommentAsync(final Long activityId, final Integer commentId) throws NotFoundException;
/**
*
* Delete a comment belonging to the authenticated user
*
*
* @param comment
* The comment to be deleted
* @return A {@link CompletableFuture} which indicates when the deletion is complete
* @throws NotFoundException
* If the comment does not exist on Strava
*/
public CompletableFuture deleteCommentAsync(final StravaComment comment) throws NotFoundException;
/**
*
* StravaActivity details, including segment efforts, splits and best efforts, are only available to the owner of the activity.
*
*
*
* By default, only "important" efforts are included. "Importance" is based on a number of undocumented factors and its value may change over time. Factors considered include: segment age, views
* and stars, if the user has hidden/shown the segment and if the effort was a PR. Note, if two activities cover the same segment, it is possible that for one activity the associated effort is
* "important" but not for the other.
*
*
*
* Note that effort ids may exceed the max value for 32-bit integers. A long integer type should be used.
*
*
*
* Each segment effort will have a hidden attribute indicating if it is "important" or not.
*
*
*
* Returns null if the activity does not exist
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The id of the {@link StravaActivity activity} to be returned
* @return Returns a detailed representation if the {@link StravaActivity activity} is owned by the requesting athlete. Returns a summary representation for all other requests.
*/
public StravaActivity getActivity(final Long activityId);
/**
*
* StravaActivity details, including segment efforts, splits and best efforts, are only available to the owner of the activity.
*
*
*
* By default, only "important" efforts are included. "Importance" is based on a number of factors and its value may change over time. Factors considered include: segment age, views and stars, if
* the user has hidden/shown the segment and if the effort was a PR. Note, if two activities cover the same segment, it is possible that for one activity the associated effort is "important" but
* not for the other.
*
*
*
* Note that effort ids may exceed the max value for 32-bit integers. A long integer type should be used.
*
*
*
* Each segment effort will have a hidden attribute indicating if it is "important" or not.
*
*
*
* Returns null if the activity does not exist
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The id of the {@link StravaActivity activity} to be returned
* @param includeAllEfforts
* (Optional) Used to include all segment efforts in the result (if omitted or false then only "important" efforts are returned).
* @return Returns a detailed representation if the {@link StravaActivity activity} is owned by the requesting athlete. Returns a summary representation for all other requests.
*/
public StravaActivity getActivity(final Long activityId, final Boolean includeAllEfforts);
/**
*
* StravaActivity details, including segment efforts, splits and best efforts, are only available to the owner of the activity.
*
*
*
* By default, only "important" efforts are included. "Importance" is based on a number of undocumented factors and its value may change over time. Factors considered include: segment age, views
* and stars, if the user has hidden/shown the segment and if the effort was a PR. Note, if two activities cover the same segment, it is possible that for one activity the associated effort is
* "important" but not for the other.
*
*
*
* Note that effort ids may exceed the max value for 32-bit integers. A long integer type should be used.
*
*
*
* Each segment effort will have a hidden attribute indicating if it is "important" or not.
*
*
*
* Returns null if the activity does not exist
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The id of the {@link StravaActivity activity} to be returned
* @return (A {@link CompletableFuture} which returns) Returns a detailed representation if the {@link StravaActivity activity} is owned by the requesting athlete. Returns a summary representation
* for all other requests.
*/
public CompletableFuture getActivityAsync(final Long activityId);
/**
*
* StravaActivity details, including segment efforts, splits and best efforts, are only available to the owner of the activity.
*
*
*
* By default, only "important" efforts are included. "Importance" is based on a number of factors and its value may change over time. Factors considered include: segment age, views and stars, if
* the user has hidden/shown the segment and if the effort was a PR. Note, if two activities cover the same segment, it is possible that for one activity the associated effort is "important" but
* not for the other.
*
*
*
* Note that effort ids may exceed the max value for 32-bit integers. A long integer type should be used.
*
*
*
* Each segment effort will have a hidden attribute indicating if it is "important" or not.
*
*
*
* Returns null if the activity does not exist
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The id of the {@link StravaActivity activity} to be returned
* @param includeAllEfforts
* (Optional) Used to include all segment efforts in the result (if omitted or false then only "important" efforts are returned).
* @return (A {@link CompletableFuture} which returns) Returns a detailed representation if the {@link StravaActivity activity} is owned by the requesting athlete. Returns a summary representation
* for all other requests.
*/
public CompletableFuture getActivityAsync(final Long activityId, final Boolean includeAllEfforts);
/**
*
* Kudo an activity (kudo is given by the authenticated athlete). You can do this multiple times, but the activity only receives one kudos.
*
*
*
* Kudos posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
* @param activityId
* Identifier of the activity to be kudoed.
* @throws NotFoundException
* If the activity does not exist on Strava
*/
public void giveKudos(final Long activityId) throws NotFoundException;
/**
*
* Kudo an activity (kudo is given by the authenticated athlete). You can do this multiple times, but the activity only receives one kudos.
*
*
*
* Kudos posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
* @param activityId
* Identifier of the activity to be kudoed.
* @return A {@link CompletableFuture} which indicates when the kudos has been given
* @throws NotFoundException
* If the activity does not exist on Strava
*/
public CompletableFuture giveKudosAsync(final Long activityId) throws NotFoundException;
/**
*
* Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.
*
*
*
* {@link StravaComment Comment} posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.
*
*
*
* Pagination is not supported. Only the first page is returned by Strava.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Returns an empty array if the {@link StravaActivity} does not contain any {@link StravaComment comments}
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/comments
*
*
* @see http://strava.github.io/api/v3/comments/
*
* @param activityId
* The id of the {@link StravaActivity} for which {@link StravaComment comments} should be returned
* @return List of comments
*/
public List listActivityComments(final Long activityId);
/**
*
* Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.
*
*
*
* StravaComment posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.
*
*
*
* Pagination is not supported. Only the first page is returned by Strava.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Returns an empty array if the {@link StravaActivity} does not contain any {@link StravaComment comments}
*
*
*
* Pagination is not supported. Returns only the first page of activities.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/comments
*
*
* @see http://strava.github.io/api/v3/comments/
*
* @param activityId
* The id of the {@link StravaActivity} for which {@link StravaComment comments} should be returned
* @param markdown
* (Optional) Include markdown in comments (default is false - i.e. filter out
* @return List of comments
*/
public List listActivityComments(final Long activityId, final Boolean markdown);
/**
*
* Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.
*
*
*
* StravaComment posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Returns an empty array if the {@link StravaActivity} does not contain any {@link StravaComment comments}
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/comments
*
*
* @see http://strava.github.io/api/v3/comments/
*
* @param activityId
* The id of the {@link StravaActivity} for which {@link StravaComment comments} should be returned
* @param markdown
* (Optional) Include markdown in comments (default is false - i.e. filter out
* @param pagingInstruction
* (Optional) The page to be returned
* @return List of comments
*/
public List listActivityComments(final Long activityId, final Boolean markdown, final Paging pagingInstruction);
/**
*
* Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.
*
*
*
* {@link StravaComment Comment} posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Returns an empty array if the {@link StravaActivity} does not contain any {@link StravaComment comments}
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/comments
*
*
* @see http://strava.github.io/api/v3/comments/
*
* @param activityId
* The id of the {@link StravaActivity} for which {@link StravaComment comments} should be returned
* @param pagingInstruction
* (Optional) Paging instructions. If not provided then the first page is returned.
* @return List of comments
*/
public List listActivityComments(final Long activityId, final Paging pagingInstruction);
/**
*
* Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.
*
*
*
* {@link StravaComment Comment} posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.
*
*
*
* Pagination is not supported. Only the first page is returned by Strava.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Returns an empty array if the {@link StravaActivity} does not contain any {@link StravaComment comments}
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/comments
*
*
* @see http://strava.github.io/api/v3/comments/
*
* @param activityId
* The id of the {@link StravaActivity} for which {@link StravaComment comments} should be returned
* @return (A {@link CompletableFuture} which returns) List of comments
*/
public CompletableFuture> listActivityCommentsAsync(final Long activityId);
/**
*
* Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.
*
*
*
* StravaComment posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.
*
*
*
* Pagination is not supported. Only the first page is returned by Strava.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Returns an empty array if the {@link StravaActivity} does not contain any {@link StravaComment comments}
*
*
*
* Pagination is not supported. Returns only the first page of activities.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/comments
*
*
* @see http://strava.github.io/api/v3/comments/
*
* @param activityId
* The id of the {@link StravaActivity} for which {@link StravaComment comments} should be returned
* @param markdown
* (Optional) Include markdown in comments (default is false - i.e. filter out
* @return (A {@link CompletableFuture} which returns) List of comments
*/
public CompletableFuture> listActivityCommentsAsync(final Long activityId, final Boolean markdown);
/**
*
* Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.
*
*
*
* StravaComment posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Returns an empty array if the {@link StravaActivity} does not contain any {@link StravaComment comments}
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/comments
*
*
* @see http://strava.github.io/api/v3/comments/
*
* @param activityId
* The id of the {@link StravaActivity} for which {@link StravaComment comments} should be returned
* @param markdown
* (Optional) Include markdown in comments (default is false - i.e. filter out
* @param pagingInstruction
* (Optional) The page to be returned
* @return (A {@link CompletableFuture} which returns) List of comments
*/
public CompletableFuture> listActivityCommentsAsync(final Long activityId, final Boolean markdown, final Paging pagingInstruction);
/**
*
* Comments on an activity can be viewed by any user. However, only internal applications are allowed to create or delete them.
*
*
*
* {@link StravaComment Comment} posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of comments is included in the activity summary and detail responses. Use this endpoint to retrieve a list of comments left on a given activity.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Returns an empty array if the {@link StravaActivity} does not contain any {@link StravaComment comments}
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/comments
*
*
* @see http://strava.github.io/api/v3/comments/
*
* @param activityId
* The id of the {@link StravaActivity} for which {@link StravaComment comments} should be returned
* @param pagingInstruction
* (Optional) Paging instructions. If not provided then the first page is returned.
* @return (A {@link CompletableFuture} which returns) List of comments
*/
public CompletableFuture> listActivityCommentsAsync(final Long activityId, final Paging pagingInstruction);
/**
*
* A kudos is Strava's version of a 'like' or '+1'. The number of kudos on an activity is returned with the activity summary.
*
*
*
* Kudos posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of kudos is included in the activity summary and detailed representations. This endpoint is for retrieving more detailed information on the athletes who have left kudos and can only
* be accessed by the owner of the activity.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Pagination is not supported. Only the first page is returned by Strava.
*
*
* @see http://strava.github.io/api/v3/kudos/
*
* @param activityId
* The id of the {@link StravaActivity} for which kudoers are to be listed
* @return Returns an array of {@link StravaAthlete athlete} summary objects.
*/
public List listActivityKudoers(final Long activityId);
/**
*
* A kudos is Strava's version of a 'like' or '+1'. The number of kudos on an activity is returned with the activity summary.
*
*
*
* Kudos posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of kudos is included in the activity summary and detailed representations. This endpoint is for retrieving more detailed information on the athletes who have left kudos and can only
* be accessed by the owner of the activity.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Pagination is supported.
*
*
* @see http://strava.github.io/api/v3/kudos/
*
* @param activityId
* The id of the {@link StravaActivity} for which kudoers are to be listed
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaAthlete athlete} summary objects.
*/
public List listActivityKudoers(final Long activityId, final Paging pagingInstruction);
/**
*
* A kudos is Strava's version of a 'like' or '+1'. The number of kudos on an activity is returned with the activity summary.
*
*
*
* Kudos posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of kudos is included in the activity summary and detailed representations. This endpoint is for retrieving more detailed information on the athletes who have left kudos and can only
* be accessed by the owner of the activity.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Pagination is not supported. Only the first page is returned by Strava.
*
*
* @see http://strava.github.io/api/v3/kudos/
*
* @param activityId
* The id of the {@link StravaActivity} for which kudoers are to be listed
* @return (A {@link CompletableFuture} which returns) Returns an array of {@link StravaAthlete athlete} summary objects.
*/
public CompletableFuture> listActivityKudoersAsync(final Long activityId);
/**
*
* A kudos is Strava's version of a 'like' or '+1'. The number of kudos on an activity is returned with the activity summary.
*
*
*
* Kudos posting can be enabled on a per application basis, email developers -at- strava.com for more information.
*
*
*
* The number of kudos is included in the activity summary and detailed representations. This endpoint is for retrieving more detailed information on the athletes who have left kudos and can only
* be accessed by the owner of the activity.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Pagination is supported.
*
*
* @see http://strava.github.io/api/v3/kudos/
*
* @param activityId
* The id of the {@link StravaActivity} for which kudoers are to be listed
* @param pagingInstruction
* (Optional) The page to be returned
* @return (A {@link CompletableFuture} which returns) Returns an array of {@link StravaAthlete athlete} summary objects.
*/
public CompletableFuture> listActivityKudoersAsync(final Long activityId, final Paging pagingInstruction);
/**
*
* This resource will return all laps for an activity. Laps are triggered by athletes using their respective devices, such as Garmin watches.
*
*
*
* Returns null if the activity does not exist
*
*
*
* Pagination is not supported. Returns all the laps for the activity.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/laps
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The id of the {@link StravaActivity} for which laps should be returned
* @return Returns an array of {@link StravaLap lap} effort summaries
*/
public List listActivityLaps(final Long activityId);
/**
*
* This resource will return all laps for an activity. Laps are triggered by athletes using their respective devices, such as Garmin watches.
*
*
*
* Returns null if the activity does not exist
*
*
*
* Pagination is not supported. Returns all the laps for the activity.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/laps
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The id of the {@link StravaActivity} for which laps should be returned
* @return (A {@link CompletableFuture} which returns) Returns an array of {@link StravaLap lap} effort summaries
*/
public CompletableFuture> listActivityLapsAsync(final Long activityId);
/**
*
* Photos are external objects associated with an activity. Currently, the only external photo source is Instagram.
*
*
*
* Note that Instagram does not provide taken_at information.
*
*
*
* The number of photos is included in the activity summary and detail responses. Use this endpoint to retrieve a list of photos associated with this activity. This endpoint can only be accessed
* by the owner of the activity.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Pagination is not supported. Returns all photos associated with the activity.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/photos
*
*
* @see http://strava.github.io/api/v3/photos/
*
* @param activityId
* The id of the {@link StravaActivity} for which photos are to be listed
* @return Returns an array of {@link StravaPhoto photo} objects.
*/
public List listActivityPhotos(final Long activityId);
/**
*
* Photos are external objects associated with an activity. Currently, the only external photo source is Instagram.
*
*
*
* Note that Instagram does not provide taken_at information.
*
*
*
* The number of photos is included in the activity summary and detail responses. Use this endpoint to retrieve a list of photos associated with this activity. This endpoint can only be accessed
* by the owner of the activity.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Pagination is not supported. Returns all photos associated with the activity.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/photos
*
*
* @see http://strava.github.io/api/v3/photos/
*
* @param activityId
* The id of the {@link StravaActivity} for which photos are to be listed
* @return (A {@link CompletableFuture} which returns) Returns an array of {@link StravaPhoto photo} objects.
*/
public CompletableFuture> listActivityPhotosAsync(final Long activityId);
/**
*
* Heartrate and power zones are set by the {@link StravaAthlete athlete}. This endpoint returns the time (seconds) in each zone for the {@link StravaActivity activity}.
*
*
*
* The distribution is not customizable.
*
*
*
* Requires an access token associated with the owner of the activity and the owner must be a premium user.
*
*
*
* Returns null if the activity does not exist
*
*
*
* Pagination is not supported. Returns all activity zones for the activity.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/zones
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The id of the {@link StravaActivity activity} for which zones should be returned
* @return Returns an array of {@link StravaActivityZone activity zones} for the {@link StravaActivity} identified
*/
public List listActivityZones(final Long activityId);
/**
*
* Heartrate and power zones are set by the {@link StravaAthlete athlete}. This endpoint returns the time (seconds) in each zone for the {@link StravaActivity activity}.
*
*
*
* The distribution is not customizable.
*
*
*
* Requires an access token associated with the owner of the activity and the owner must be a premium user.
*
*
*
* Returns null if the activity does not exist
*
*
*
* Pagination is not supported. Returns all activity zones for the activity.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/:id/zones
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The id of the {@link StravaActivity activity} for which zones should be returned
* @return (A {@link CompletableFuture} which returns) Returns an array of {@link StravaActivityZone activity zones} for the {@link StravaActivity} identified
*/
public CompletableFuture> listActivityZonesAsync(final Long activityId);
/**
*
* List ALL comments on an activity, regardless of how many there are
*
*
*
* Returns null if the activity does not exist
*
*
*
* Pagination is not supported - this method just returns ALL comments
*
*
*
* USE WITH CAUTION - ACTIVITIES WITH MANY COMMENTS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
* @param activityId
* The activity whose comments should be listed
* @return All comments on the activity
*/
public List listAllActivityComments(final Long activityId);
/**
*
* List ALL comments on an activity, regardless of how many there are
*
*
*
* Returns null if the activity does not exist
*
*
*
* Pagination is not supported - this method just returns ALL comments
*
*
*
* USE WITH CAUTION - ACTIVITIES WITH MANY COMMENTS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
* @param activityId
* The activity whose comments should be listed
* @return (A {@link CompletableFuture} which returns) All comments on the activity
*/
public CompletableFuture> listAllActivityCommentsAsync(final Long activityId);
/**
*
* List ALL kudoers on an activity, regardless of how many there are
*
*
*
* Returns null if the activity does not exist
*
*
*
* Pagination is not supported - this method just returns ALL kudoers
*
*
*
* USE WITH CAUTION - ACTIVITIES WITH MANY KUDOS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
* @param activityId
* The activity whose kudoers should be listed
* @return All athletes who have kudoed the activity
*/
public List listAllActivityKudoers(final Long activityId);
/**
*
* List ALL kudoers on an activity, regardless of how many there are
*
*
*
* Returns null if the activity does not exist
*
*
*
* Pagination is not supported - this method just returns ALL kudoers
*
*
*
* USE WITH CAUTION - ACTIVITIES WITH MANY KUDOS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
* @param activityId
* The activity whose kudoers should be listed
* @return (A {@link CompletableFuture} which returns) All athletes who have kudoed the activity
*/
public CompletableFuture> listAllActivityKudoersAsync(final Long activityId);
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* Pagination is NOT supported. USE WITH CAUTION. ALL activities for the athlete will be returned, regardless of how many calls to the Strava API are required to achieve this.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @return Returns an array of {@link StravaActivity} summary representations sorted newest first by default.
*/
public List listAllAuthenticatedAthleteActivities();
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* Pagination is NOT supported. USE WITH CAUTION. ALL activities for the athlete will be returned, regardless of how many calls to the Strava API are required to achieve this.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param before
* Return only rides started BEFORE this date/time
* @param after
* Return only rides started AFTER this data/time
* @return Returns an array of {@link StravaActivity} summary representations sorted newest first by default.
*/
public List listAllAuthenticatedAthleteActivities(final LocalDateTime before, final LocalDateTime after);
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* Pagination is NOT supported. USE WITH CAUTION. ALL activities for the athlete will be returned, regardless of how many calls to the Strava API are required to achieve this.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @return (A {@link CompletableFuture} which returns) Returns an array of {@link StravaActivity} summary representations sorted newest first by default.
*/
public CompletableFuture> listAllAuthenticatedAthleteActivitiesAsync();
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* Pagination is NOT supported. USE WITH CAUTION. ALL activities for the athlete will be returned, regardless of how many calls to the Strava API are required to achieve this.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param before
* Return only rides started BEFORE this date/time
* @param after
* Return only rides started AFTER this data/time
* @return (A {@link CompletableFuture} which returns) Returns an array of {@link StravaActivity} summary representations sorted newest first by default.
*/
public CompletableFuture> listAllAuthenticatedAthleteActivitiesAsync(final LocalDateTime before, final LocalDateTime after);
/**
*
* List the recent activities performed by those the current authenticated {@link StravaAthlete} is following.
*
*
*
* Pagination is not supported - this method just returns ALL friends' activities (although it is restricted by Strava to the last 200)
*
*
*
* USE WITH CAUTION - ACTIVITIES WITH MANY RELATED ACTIVITIES WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* URL GET https://www.strava.com/api/v3/activities/following
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @return Returns an array of activity summary representations sorted newest first by start_date.
*/
public List listAllFriendsActivities();
/**
*
* List the recent activities performed by those the current authenticated {@link StravaAthlete} is following.
*
*
*
* Pagination is not supported - this method just returns ALL friends' activities (although it is restricted by Strava to the last 200)
*
*
*
* USE WITH CAUTION - ACTIVITIES WITH MANY RELATED ACTIVITIES WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* URL GET https://www.strava.com/api/v3/activities/following
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @return (A {@link CompletableFuture} which returns) Returns an array of activity summary representations sorted newest first by start_date.
*/
public CompletableFuture> listAllFriendsActivitiesAsync();
/**
*
* List ALL related activities, regardless of how many there are
*
*
*
* Returns null if the activity does not exist
*
*
*
* Pagination is not supported - this method just returns ALL related activities
*
*
*
* USE WITH CAUTION - ACTIVITIES WITH MANY RELATED ACTIVITIES WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
* @param activityId
* The activity identifier
* @return List of Strava activities that Strava has determined are related to this one
*/
public List listAllRelatedActivities(final Long activityId);
/**
*
* List ALL related activities, regardless of how many there are
*
*
*
* Returns null if the activity does not exist
*
*
*
* Pagination is not supported - this method just returns ALL related activities
*
*
*
* USE WITH CAUTION - ACTIVITIES WITH MANY RELATED ACTIVITIES WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
* @param activityId
* The activity identifier
* @return (A {@link CompletableFuture} which returns) List of Strava activities that Strava has determined are related to this one
*/
public CompletableFuture> listAllRelatedActivitiesAsync(final Long activityId);
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
*
* Pagination is not supported. Returns only the first page of activities.
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @return Returns an array of {@link StravaActivity} summary representations sorted newest first by default.
*/
public List listAuthenticatedAthleteActivities();
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* Pagination is not supported. Returns only the first page of activities.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param before
* (Optional) result will start with activities whose start_date is before this value
* @param after
* (Optional) result will start with activities whose start_date is after this value, sorted oldest first
* @return Returns an array of {@link StravaActivity} summary representations sorted newest first by default. Will be sorted oldest first if the after parameter is used.
*/
public List listAuthenticatedAthleteActivities(final LocalDateTime before, final LocalDateTime after);
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* Should be used with before, after or page/per_page. Using a combination will result in an error or unexpected results.
*
*
*
* Pagination is supported.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param before
* (Optional) result will start with activities whose start_date is before this value
* @param after
* (Optional) result will start with activities whose start_date is after this value, sorted oldest first
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaActivity} summary representations sorted newest first by default. Will be sorted oldest first if the after parameter is used.
*/
public List listAuthenticatedAthleteActivities(final LocalDateTime before, final LocalDateTime after, final Paging pagingInstruction);
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
*
* Pagination is supported
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaActivity} summary representations sorted newest first by default. Will be sorted oldest first if the after parameter is used.
*/
public List listAuthenticatedAthleteActivities(final Paging pagingInstruction);
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
*
* Pagination is not supported. Returns only the first page of activities.
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @return (A {@link CompletableFuture} which returns) Returns an array of {@link StravaActivity} summary representations sorted newest first by default.
*/
public CompletableFuture> listAuthenticatedAthleteActivitiesAsync();
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* Pagination is not supported. Returns only the first page of activities.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param before
* (Optional) result will start with activities whose start_date is before this value
* @param after
* (Optional) result will start with activities whose start_date is after this value, sorted oldest first
* @return (A {@link CompletableFuture} which returns) Returns an array of {@link StravaActivity} summary representations sorted newest first by default. Will be sorted oldest first if the after
* parameter is used.
*/
public CompletableFuture> listAuthenticatedAthleteActivitiesAsync(final LocalDateTime before, final LocalDateTime after);
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* Should be used with before, after or page/per_page. Using a combination will result in an error or unexpected results.
*
*
*
* Pagination is supported.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param before
* (Optional) result will start with activities whose start_date is before this value
* @param after
* (Optional) result will start with activities whose start_date is after this value, sorted oldest first
* @param pagingInstruction
* (Optional) The page to be returned
* @return (A {@link CompletableFuture} which returns) Returns an array of {@link StravaActivity} summary representations sorted newest first by default. Will be sorted oldest first if the after
* parameter is used.
*/
public CompletableFuture> listAuthenticatedAthleteActivitiesAsync(final LocalDateTime before, final LocalDateTime after, final Paging pagingInstruction);
/**
*
* This endpoint returns a list of {@link StravaActivity activities} for the authenticated {@link StravaAthlete}.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete/activities
*
*
*
* Pagination is supported
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param pagingInstruction
* (Optional) The page to be returned
* @return (A {@link CompletableFuture} which returns) Returns an array of {@link StravaActivity} summary representations sorted newest first by default. Will be sorted oldest first if the after
* parameter is used.
*/
public CompletableFuture> listAuthenticatedAthleteActivitiesAsync(final Paging pagingInstruction);
/**
*
* List the recent activities performed by those the current authenticated {@link StravaAthlete} is following.
*
*
*
* Pagination is not supported. Only the first page is returned by Strava.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/following
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @return Returns an array of activity summary representations sorted newest first by start_date.
*/
public List listFriendsActivities();
/**
*
* List the recent activities performed by those the current authenticated {@link StravaAthlete} is following.
*
*
*
* Pagination is supported. However, results are limited to the last 200 total activities.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/following
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of activity summary representations sorted newest first by start_date.
*/
public List listFriendsActivities(final Paging pagingInstruction);
/**
*
* List the recent activities performed by those the current authenticated {@link StravaAthlete} is following.
*
*
*
* Pagination is not supported. Only the first page is returned by Strava.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/following
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @return (A {@link CompletableFuture} which returns) Returns an array of activity summary representations sorted newest first by start_date.
*/
public CompletableFuture> listFriendsActivitiesAsync();
/**
*
* List the recent activities performed by those the current authenticated {@link StravaAthlete} is following.
*
*
*
* Pagination is supported. However, results are limited to the last 200 total activities.
*
*
*
* URL GET https://www.strava.com/api/v3/activities/following
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param pagingInstruction
* (Optional) The page to be returned
* @return (A {@link CompletableFuture} which returns) Returns an array of activity summary representations sorted newest first by start_date.
*/
public CompletableFuture> listFriendsActivitiesAsync(final Paging pagingInstruction);
/**
*
* Returns the activities that were matched as "with this group". The number equals activity.athlete_count-1.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Pagination is not supported. Only the first page is returned by Strava.
*
*
* @param activityId
* StravaActivity id for which related activities should be listed
* @return List of related activities (not including the main activity)
*/
public List listRelatedActivities(final Long activityId);
/**
*
* Returns the activities that were matched as "with this group". The number equals activity.athlete_count-1.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Pagination is supported.
*
*
* @param activityId
* StravaActivity id for which related activities should be listed
* @param pagingInstruction
* Paging instructions
* @return List of related activities (not including the main activity)
*/
public List listRelatedActivities(final Long activityId, final Paging pagingInstruction);
/**
*
* Returns the activities that were matched as "with this group". The number equals activity.athlete_count-1.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Pagination is not supported. Only the first page is returned by Strava.
*
*
* @param activityId
* StravaActivity id for which related activities should be listed
* @return (A {@link CompletableFuture} which returns) List of related activities (not including the main activity)
*/
public CompletableFuture> listRelatedActivitiesAsync(final Long activityId);
/**
*
* Returns the activities that were matched as "with this group". The number equals activity.athlete_count-1.
*
*
*
* Returns null if the {@link StravaActivity} does not exist
*
*
*
* Pagination is supported.
*
*
* @param activityId
* StravaActivity id for which related activities should be listed
* @param pagingInstruction
* Paging instructions
* @return (A {@link CompletableFuture} which returns) List of related activities (not including the main activity)
*/
public CompletableFuture> listRelatedActivitiesAsync(final Long activityId, final Paging pagingInstruction);
/**
*
* Requires write permissions, as requested during the authorization process.
*
*
*
* Only updates name, type, private, commute, trainer, gear_id and description
*
*
*
* Returns null if the activity doesn't exist on Strava
*
*
*
* URL PUT https://www.strava.com/api/v3/activities/:id
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The identifier of the activity to be updated
* @param activity
* The {@link StravaActivityUpdate} to be updated
* @return Returns a detailed representation of the updated {@link StravaActivity}.
* @throws NotFoundException
* If the activity with the given id does not exist
*
*/
public StravaActivity updateActivity(final Long activityId, final StravaActivityUpdate activity) throws NotFoundException;
/**
*
* Requires write permissions, as requested during the authorization process.
*
*
*
* Only updates name, type, private, commute, trainer, gear_id and description
*
*
*
* Returns null if the activity doesn't exist on Strava
*
*
*
* URL PUT https://www.strava.com/api/v3/activities/:id
*
*
* @see http://strava.github.io/api/v3/activities/
*
* @param activityId
* The identifier of the activity to be updated
* @param activity
* The {@link StravaActivityUpdate} to be updated
* @return (A {@link CompletableFuture} which returns) Returns a detailed representation of the updated {@link StravaActivity}.
* @throws NotFoundException
* If the activity with the given id does not exist
*
*/
public CompletableFuture updateActivityAsync(final Long activityId, final StravaActivityUpdate activity) throws NotFoundException;
}