javastrava.api.v3.service.ActivityService Maven / Gradle / Ivy
Show all versions of javastrava-api Show documentation
package javastrava.api.v3.service;
import java.time.LocalDateTime;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import javastrava.api.v3.model.StravaActivity;
import javastrava.api.v3.model.StravaActivityUpdate;
import javastrava.api.v3.model.StravaActivityZone;
import javastrava.api.v3.model.StravaAthlete;
import javastrava.api.v3.model.StravaComment;
import javastrava.api.v3.model.StravaLap;
import javastrava.api.v3.model.StravaPhoto;
import javastrava.api.v3.service.exception.BadRequestException;
import javastrava.api.v3.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.
*
*
*
* Comment posting must be explicitly authorised by Strava for your application.
*
*
*
* 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.
*
*
*
* Comment posting must be explicitly authorised by Strava for your application.
*
*
*
* 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}
*
*
*
* 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}
*
*
*
* 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.
*
*
* @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.
*
*
* @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 id
* StravaActivity id for which related activities should be listed
* @return List of related activities (not including the main activity)
*/
public List listRelatedActivities(final Long id);
/**
*
* 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 id
* 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 id, 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 id
* 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 id);
/**
*
* 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 id
* 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 id, 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;
}