javastrava.service.AthleteService Maven / Gradle / Ivy
Show all versions of javastrava-api Show documentation
package javastrava.service;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import javastrava.model.StravaAthlete;
import javastrava.model.StravaAthleteZones;
import javastrava.model.StravaSegmentEffort;
import javastrava.model.StravaStatistics;
import javastrava.model.reference.StravaGender;
import javastrava.service.exception.UnauthorizedException;
import javastrava.util.Paging;
/**
* StravaAthlete related services
*
* @see http://strava.github.io/api/v3/athlete/
* @author Dan Shannon
*
*/
public interface AthleteService extends StravaService {
/**
*
* This request is used to retrieve information about any {@link StravaAthlete athlete} on Strava.
*
*
*
* Returns null if athlete does not exist
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id
*
*
* @see http://strava.github.io/api/v3/athlete/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} to be returned
* @return Returns a summary representation of the {@link StravaAthlete athlete} even if the indicated athlete matches the authenticated athlete.
*/
public StravaAthlete getAthlete(final Integer athleteId);
/**
*
* This request is used to retrieve information about any {@link StravaAthlete athlete} on Strava.
*
*
*
* Returns null if athlete does not exist
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id
*
*
* @see http://strava.github.io/api/v3/athlete/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} to be returned
* @return Returns a summary representation of the {@link StravaAthlete athlete} even if the indicated athlete matches the authenticated athlete.
*/
public CompletableFuture getAthleteAsync(final Integer athleteId);
/**
*
* This request is used to retrieve information about the currently authenticated {@link StravaAthlete athlete}.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete
*
*
* @see http://strava.github.io/api/v3/athlete/
* @return Returns a detailed representation of the {@link StravaAthlete athlete}
* @throws UnauthorizedException
* If the service's access token is invalid
*/
public StravaAthlete getAuthenticatedAthlete();
/**
*
* This request is used to retrieve information about the currently authenticated {@link StravaAthlete athlete}.
*
*
*
* URL GET https://www.strava.com/api/v3/athlete
*
*
* @see http://strava.github.io/api/v3/athlete/
* @return Returns a detailed representation of the {@link StravaAthlete athlete}
* @throws UnauthorizedException
* If the service's access token is invalid
*/
public CompletableFuture getAuthenticatedAthleteAsync();
/**
*
* Returns the current athlete’s heart rate and power zones. The min for Zone 1 is always 0 and the max for Zone 5 is always -1.
*
*
*
* Premium members who have set a functional threshold power (ftp) will see their power zones. Power zones are a Premium-only feature. Free members will not see the power part of this endpoint.
*
*
* @return The athlete zones object
*/
public StravaAthleteZones getAuthenticatedAthleteZones();
/**
*
* Returns the current athlete’s heart rate and power zones. The min for Zone 1 is always 0 and the max for Zone 5 is always -1.
*
*
*
* Premium members who have set a functional threshold power (ftp) will see their power zones. Power zones are a Premium-only feature. Free members will not see the power part of this endpoint.
*
*
* @return The athlete zones object (via a {@link CompletableFuture})
*/
public CompletableFuture getAuthenticatedAthleteZonesAsync();
/**
*
* Convenience method for returning ALL of an athlete's friends
*
*
*
* Returns ALL the athlete's friends, regardless of how many there are
*
*
*
* Pagination is NOT supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* USE WITH CAUTION - ATHLETES WITH MANY FRIENDS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param athleteId
* The athlete whose friends are to be listed
* @return List of athlete's friends, or null if the athlete does not exist
*/
public List listAllAthleteFriends(final Integer athleteId);
/**
*
* Convenience method for returning ALL of an athlete's friends
*
*
*
* Returns ALL the athlete's friends, regardless of how many there are
*
*
*
* Pagination is NOT supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* USE WITH CAUTION - ATHLETES WITH MANY FRIENDS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param athleteId
* The athlete whose friends are to be listed
* @return List of athlete's friends, or null if the athlete does not exist
*/
public CompletableFuture> listAllAthleteFriendsAsync(final Integer athleteId);
/**
*
* Convenience method for returning ALL of an athlete's KOM's
*
*
*
* Returns ALL the athlete's KOM's, regardless of how many there are
*
*
*
* Pagination is NOT supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* USE WITH CAUTION - ATHLETES WITH MANY KOMS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/koms
*
*
* @see http://strava.github.io/api/v3/athlete/
*
* @param athleteId
* The athlete whose KOM'ss are to be listed
* @return List of segment efforts for which the athlete is KOM, or null if the athlete does not exist
*/
public List listAllAthleteKOMs(final Integer athleteId);
/**
*
* Convenience method for returning ALL of an athlete's KOM's
*
*
*
* Returns ALL the athlete's KOM's, regardless of how many there are
*
*
*
* Pagination is NOT supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* USE WITH CAUTION - ATHLETES WITH MANY KOMS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/koms
*
*
* @see http://strava.github.io/api/v3/athlete/
*
* @param athleteId
* The athlete whose KOM'ss are to be listed
* @return List of segment efforts for which the athlete is KOM, or null if the athlete does not exist
*/
public CompletableFuture> listAllAthleteKOMsAsync(final Integer athleteId);
/**
*
* Convenience method for returning ALL of the athletes that both the authenticated athlete and the given athlete are following
*
*
*
* Returns ALL the followers, regardless of how many there are
*
*
*
* Pagination is NOT supported.
*
*
*
* USE WITH CAUTION - ATHLETES WITH MANY FRIENDS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/both-following
*
*
* @param athleteId
* The athlete who the list is to be generated for
*
* @see http://strava.github.io/api/v3/follow/
*
* @return List of the authenticated athlete's friends
*/
public List listAllAthletesBothFollowing(final Integer athleteId);
/**
*
* Convenience method for returning ALL of the athletes that both the authenticated athlete and the given athlete are following
*
*
*
* Returns ALL the followers, regardless of how many there are
*
*
*
* Pagination is NOT supported.
*
*
*
* USE WITH CAUTION - ATHLETES WITH MANY FRIENDS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/both-following
*
*
* @param athleteId
* The athlete who the list is to be generated for
*
* @see http://strava.github.io/api/v3/follow/
*
* @return List of the authenticated athlete's friends
*/
public CompletableFuture> listAllAthletesBothFollowingAsync(final Integer athleteId);
/**
*
* Convenience method for returning ALL of the authenticated athlete's friends
*
*
*
* Returns ALL the authenticated athlete's friends, regardless of how many there are
*
*
*
* Pagination is NOT supported.
*
*
*
* USE WITH CAUTION - ATHLETES WITH MANY FRIENDS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @return List of the authenticated athlete's friends
*/
public List listAllAuthenticatedAthleteFriends();
/**
*
* Convenience method for returning ALL of the authenticated athlete's friends
*
*
*
* Returns ALL the authenticated athlete's friends, regardless of how many there are
*
*
*
* Pagination is NOT supported.
*
*
*
* USE WITH CAUTION - ATHLETES WITH MANY FRIENDS WILL REQUIRE MANY CALLS TO THE STRAVA API
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @return List of the authenticated athlete's friends
*/
public CompletableFuture> listAllAuthenticatedAthleteFriendsAsync();
/**
*
* Friends are users an {@link StravaAthlete athlete} is following. The activities owned by these users will appear in the current athlete's activity feed.
*
*
*
* If the indicated athlete has blocked the authenticated athlete, the result will be an empty array.
*
*
*
* Pagination is not supported. Returns only the first page of athletes.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} whose friends are to be listed
* @return List of {@link StravaAthlete athletes} who are friends of the identified athlete. Will be empty if the identified athlete has blocked the currently authenticated athlete.
*/
public List listAthleteFriends(final Integer athleteId);
/**
*
* Friends are users an {@link StravaAthlete athlete} is following. The activities owned by these users will appear in the current athlete's activity feed.
*
*
*
* If the indicated athlete has blocked the authenticated athlete, the result will be an empty array.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} whose friends are to be listed
* @param pagingInstruction
* (Optional) The page to be returned
* @return List of {@link StravaAthlete athletes} who are friends of the identified athlete. Will be empty if the identified athlete has blocked the currently authenticated athlete.
*/
public List listAthleteFriends(final Integer athleteId, final Paging pagingInstruction);
/**
*
* Friends are users an {@link StravaAthlete athlete} is following. The activities owned by these users will appear in the current athlete's activity feed.
*
*
*
* If the indicated athlete has blocked the authenticated athlete, the result will be an empty array.
*
*
*
* Pagination is not supported. Returns only the first page of athletes.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} whose friends are to be listed
* @return List of {@link StravaAthlete athletes} who are friends of the identified athlete. Will be empty if the identified athlete has blocked the currently authenticated athlete.
*/
public CompletableFuture> listAthleteFriendsAsync(final Integer athleteId);
/**
*
* Friends are users an {@link StravaAthlete athlete} is following. The activities owned by these users will appear in the current athlete's activity feed.
*
*
*
* If the indicated athlete has blocked the authenticated athlete, the result will be an empty array.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} whose friends are to be listed
* @param pagingInstruction
* (Optional) The page to be returned
* @return List of {@link StravaAthlete athletes} who are friends of the identified athlete. Will be empty if the identified athlete has blocked the currently authenticated athlete.
*/
public CompletableFuture> listAthleteFriendsAsync(final Integer athleteId, final Paging pagingInstruction);
/**
*
* Returns an array of {@link StravaSegmentEffort segment efforts} representing KOMs/QOMs and course records held by the given athlete.
*
*
*
* Results are sorted by date, newest first.
*
*
*
* Pagination is not supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/koms
*
*
* @see http://strava.github.io/api/v3/athlete/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} whose KOM's are to be returned
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary representations
*/
public List listAthleteKOMs(final Integer athleteId);
/**
*
* Returns an array of {@link StravaSegmentEffort segment efforts} representing KOMs/QOMs and course records held by the given athlete.
*
*
*
* Results are sorted by date, newest first.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/koms
*
*
* @see http://strava.github.io/api/v3/athlete/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} whose KOM's are to be returned
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary representations
*/
public List listAthleteKOMs(final Integer athleteId, final Paging pagingInstruction);
/**
*
* Returns an array of {@link StravaSegmentEffort segment efforts} representing KOMs/QOMs and course records held by the given athlete.
*
*
*
* Results are sorted by date, newest first.
*
*
*
* Pagination is not supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/koms
*
*
* @see http://strava.github.io/api/v3/athlete/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} whose KOM's are to be returned
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary representations
*/
public CompletableFuture> listAthleteKOMsAsync(final Integer athleteId);
/**
*
* Returns an array of {@link StravaSegmentEffort segment efforts} representing KOMs/QOMs and course records held by the given athlete.
*
*
*
* Results are sorted by date, newest first.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/koms
*
*
* @see http://strava.github.io/api/v3/athlete/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} whose KOM's are to be returned
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaSegmentEffort segment effort} summary representations
*/
public CompletableFuture> listAthleteKOMsAsync(final Integer athleteId, final Paging pagingInstruction);
/**
*
* Retrieve the {@link StravaAthlete athletes} who both the authenticated athlete and the indicated athlete are following.
*
*
*
* Pagination is not supported. Returns only the first page of athletes.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/both-following
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} for whom the list of mutual friends is to be generated
* @return Returns an array of {@link StravaAthlete athlete} summary representations.
*/
public List listAthletesBothFollowing(final Integer athleteId);
/**
*
* Retrieve the {@link StravaAthlete athletes} who both the authenticated athlete and the indicated athlete are following.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/both-following
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} for whom the list of mutual friends is to be generated
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaAthlete athlete} summary representations.
*/
public List listAthletesBothFollowing(final Integer athleteId, final Paging pagingInstruction);
/**
*
* Retrieve the {@link StravaAthlete athletes} who both the authenticated athlete and the indicated athlete are following.
*
*
*
* Pagination is not supported. Returns only the first page of athletes.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/both-following
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} for whom the list of mutual friends is to be generated
* @return Returns an array of {@link StravaAthlete athlete} summary representations.
*/
public CompletableFuture> listAthletesBothFollowingAsync(final Integer athleteId);
/**
*
* Retrieve the {@link StravaAthlete athletes} who both the authenticated athlete and the indicated athlete are following.
*
*
*
* Pagination is supported.
*
*
*
* Returns null if athlete with the given id is not found.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/both-following
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param athleteId
* The id of the {@link StravaAthlete athlete} for whom the list of mutual friends is to be generated
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaAthlete athlete} summary representations.
*/
public CompletableFuture> listAthletesBothFollowingAsync(final Integer athleteId, final Paging pagingInstruction);
/**
*
* Friends are users the current {@link StravaAthlete athlete} is following. The activities owned by these users will appear in the current athlete's activity feed.
*
*
*
* This request is for the authenticated athlete's friends.
*
*
*
* Pagination is not supported. Returns only the first page of athletes.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @return Returns an array of {@link StravaAthlete athlete} summary representations.
*/
public List listAuthenticatedAthleteFriends();
/**
*
* Friends are users the current {@link StravaAthlete athlete} is following. The activities owned by these users will appear in the current athlete's activity feed.
*
*
*
* This request is for the authenticated athlete's friends.
*
*
*
* Pagination is supported.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaAthlete athlete} summary representations.
*/
public List listAuthenticatedAthleteFriends(final Paging pagingInstruction);
/**
*
* Friends are users the current {@link StravaAthlete athlete} is following. The activities owned by these users will appear in the current athlete's activity feed.
*
*
*
* This request is for the authenticated athlete's friends.
*
*
*
* Pagination is not supported. Returns only the first page of athletes.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @return Returns an array of {@link StravaAthlete athlete} summary representations.
*/
public CompletableFuture> listAuthenticatedAthleteFriendsAsync();
/**
*
* Friends are users the current {@link StravaAthlete athlete} is following. The activities owned by these users will appear in the current athlete's activity feed.
*
*
*
* This request is for the authenticated athlete's friends.
*
*
*
* Pagination is supported.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/friends
*
*
* @see http://strava.github.io/api/v3/follow/
*
* @param pagingInstruction
* (Optional) The page to be returned
* @return Returns an array of {@link StravaAthlete athlete} summary representations.
*/
public CompletableFuture> listAuthenticatedAthleteFriendsAsync(final Paging pagingInstruction);
/**
*
* Returns recent (last 4 weeks), year to date and all time stats for a given athlete. Only available for the authenticated athlete.
*
*
*
* This is the recommended endpoint when polling for athlete upload events.
*
*
*
* Pagination is not supported. Returns all statistics for the athlete.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/stats
*
*
* @see http://strava.github.io/api/v3/athlete/#stats
*
* @param athleteId
* The id of the athlete (must match authenticated athlete)
* @return Strava statistics object; values are in seconds and metres.
*/
public StravaStatistics statistics(final Integer athleteId);
/**
*
* Returns recent (last 4 weeks), year to date and all time stats for a given athlete. Only available for the authenticated athlete.
*
*
*
* This is the recommended endpoint when polling for athlete upload events.
*
*
*
* Pagination is not supported. Returns all statistics for the athlete.
*
*
*
* URL GET https://www.strava.com/api/v3/athletes/:id/stats
*
*
* @see http://strava.github.io/api/v3/athlete/#stats
*
* @param athleteId
* The id of the athlete (must match authenticated athlete)
* @return Strava statistics object; values are in seconds and metres.
*/
public CompletableFuture statisticsAsync(final Integer athleteId);
/**
*
* Updates the personal details of the currently authenticated {@link StravaAthlete athlete}.
*
*
*
* Requires write permissions, as requested during the authorization process.
*
*
*
* Only updates city, state, country, gender (sex) and weight.
*
*
*
* URL PUT https://www.strava.com/api/v3/athlete
*
*
* @see http://strava.github.io/api/v3/athlete/
*
* @param city
* The city where the athlete wants Strava to think they live
* @param state
* The state, county or whatever the athlete wants Strava to think they live
* @param country
* The country where the athlete wants Strava to think they live
* @param sex
* The gender the athlete wants Strava to think they identify with
* @param weight
* The weight that the athlete wants Strava to believe that they are
* @return Detailed representation of the updated athlete
*/
public StravaAthlete updateAuthenticatedAthlete(final String city, final String state, final String country, final StravaGender sex, final Float weight);
/**
*
* Updates the personal details of the currently authenticated {@link StravaAthlete athlete}.
*
*
*
* Requires write permissions, as requested during the authorization process.
*
*
*
* Only updates city, state, country, gender (sex) and weight.
*
*
*
* URL PUT https://www.strava.com/api/v3/athlete
*
*
* @see http://strava.github.io/api/v3/athlete/
*
* @param city
* The city where the athlete wants Strava to think they live
* @param state
* The state, county or whatever the athlete wants Strava to think they live
* @param country
* The country where the athlete wants Strava to think they live
* @param sex
* The gender the athlete wants Strava to think they identify with
* @param weight
* The weight that the athlete wants Strava to believe that they are
* @return Detailed representation of the updated athlete
*/
public CompletableFuture updateAuthenticatedAthleteAsync(final String city, final String state, final String country, final StravaGender sex, final Float weight);
}