javastrava.api.RouteAPI Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of javastrava-api Show documentation
Java implementation of the Strava API
The newest version!
package javastrava.api;

import javastrava.api.async.StravaAPICallback;
import javastrava.auth.ref.AuthorisationScope;
import javastrava.model.StravaRoute;
import javastrava.service.exception.BadRequestException;
import javastrava.service.exception.NotFoundException;
import javastrava.service.exception.UnauthorizedException;
import retrofit.client.Response;
import retrofit.http.GET;
import retrofit.http.Path;
import retrofit.http.Query;

/**
 * 
 * Routes are manually-created paths made up of sections called legs. Currently it is only possible to create routes using the Routebuilder web interface.
 * 
 *
 * @author Dan Shannon
 *
 */
public interface RouteAPI {
	/**
	 * 
	 * This request is used to retrieve details about a route. Private routes can only be accessed if owned by the authenticating user and the token has {@link AuthorisationScope#VIEW_PRIVATE
	 * view_private} permissions. For raw data associated with a route see route streams.
	 * 
	 *
	 * @param routeId
	 *            The identifier of the route to retrieve
	 * @return The route
	 * @throws NotFoundException
	 *             If the route does not exist
	 * @throws BadRequestException
	 *             If the id is not an integer
	 * @throws UnauthorizedException
	 *             If the route is private and the token has {@link AuthorisationScope#VIEW_PRIVATE view_private}
	 */
	@GET("/routes/{id}")
	public StravaRoute getRoute(@Path("id") Integer routeId) throws NotFoundException, BadRequestException, UnauthorizedException;

	/**
	 * 
	 * This request is used to retrieve details about a route. Private routes can only be accessed if owned by the authenticating user and the token has {@link AuthorisationScope#VIEW_PRIVATE
	 * view_private} permissions. For raw data associated with a route see route streams.
	 * 
	 *
	 * @param routeId
	 *            The identifier of the route to retrieve
	 * @param callback
	 *            The callback to execute to retrieve the route
	 * @throws NotFoundException
	 *             If the route does not exist
	 * @throws BadRequestException
	 *             If the id is not an integer
	 * @throws UnauthorizedException
	 *             If the route is private and the token has {@link AuthorisationScope#VIEW_PRIVATE view_private}
	 */
	@GET("/routes/{id}")
	public void getRoute(@Path("id") Integer routeId, StravaAPICallback callback);

	/**
	 * 
	 * This request is used to retrieve details about a route. Private routes can only be accessed if owned by the authenticating user and the token has {@link AuthorisationScope#VIEW_PRIVATE
	 * view_private} permissions. For raw data associated with a route see route streams.
	 * 
	 *
	 * @param routeId
	 *            The identifier of the route to retrieve
	 * @return The route
	 * @throws NotFoundException
	 *             If the route does not exist
	 * @throws BadRequestException
	 *             If the id is not an integer
	 * @throws UnauthorizedException
	 *             If the route is private and the token has {@link AuthorisationScope#VIEW_PRIVATE view_private}
	 */
	@GET("/routes/{id}")
	public Response getRouteRaw(@Path("id") Integer routeId) throws NotFoundException, BadRequestException, UnauthorizedException;

	/**
	 * 
	 * Lists a specific athlete’s routes. Private routes will only be included if the authenticating user is viewing their own routes and the token has {@link AuthorisationScope#VIEW_PRIVATE
	 * view_private} permissions.
	 * 
	 *
	 * 
	 * Pagination is supported.
	 * 
	 *
	 * @param id
	 *            The athlete id whose routes should be listed
	 * @param page
	 *            Page of the results to return
	 * @param perPage
	 *            Number of items per page
	 * @return The array of routes
	 * @throws NotFoundException
	 *             If the athlete does not exist
	 * @throws BadRequestException
	 *             If the paging parameters are invalid
	 */
	@GET("/athletes/{id}/routes")
	public StravaRoute[] listAthleteRoutes(@Path("id") Integer id, @Query("page") Integer page, @Query("per_page") Integer perPage) throws NotFoundException, BadRequestException;

	/**
	 * 
	 * Lists a specific athlete’s routes. Private routes will only be included if the authenticating user is viewing their own routes and the token has {@link AuthorisationScope#VIEW_PRIVATE
	 * view_private} permissions.
	 * 
	 *
	 * 
	 * Pagination is supported.
	 * 
	 *
	 * @param id
	 *            The athlete id whose routes should be listed
	 * @param callback
	 *            The callback to execute to return the routes
	 * @param page
	 *            Page of the results to return
	 * @param perPage
	 *            Number of items per page
	 * @throws NotFoundException
	 *             If the athlete does not exist
	 * @throws BadRequestException
	 *             If the paging parameters are invalid
	 */
	@GET("/athletes/{id}/routes")
	public void listAthleteRoutes(@Path("id") Integer id, @Query("page") Integer page, @Query("per_page") Integer perPage, StravaAPICallback callback)
			throws NotFoundException, BadRequestException;

	/**
	 * 
	 * Lists a specific athlete’s routes. Private routes will only be included if the authenticating user is viewing their own routes and the token has {@link AuthorisationScope#VIEW_PRIVATE
	 * view_private} permissions.
	 * 
	 *
	 * 
	 * Pagination is supported.
	 * 
	 *
	 * @param id
	 *            The athlete id whose routes should be listed
	 * @param page
	 *            Page of the results to return
	 * @param perPage
	 *            Number of items per page
	 * @throws NotFoundException
	 *             If the athlete does not exist
	 * @throws BadRequestException
	 *             If the paging parameters are invalid
	 * @return The route
	 */
	@GET("/athletes/{id}/routes")
	public Response listAthleteRoutesRaw(@Path("id") Integer id, @Query("page") Integer page, @Query("per_page") Integer perPage) throws NotFoundException, BadRequestException;
}