README.md in strava-ruby-client-0.4.3 vs README.md in strava-ruby-client-1.0.0

- old
+ new

@@ -1,7 +1,6 @@ -Strava Ruby Client -================== +# Strava Ruby Client [![Gem Version](https://badge.fury.io/rb/strava-ruby-client.svg)](https://badge.fury.io/rb/strava-ruby-client) [![Test](https://github.com/dblock/strava-ruby-client/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/dblock/strava-ruby-client/actions/workflows/test.yml) A complete Ruby client for the [Strava API v3](https://developers.strava.com). @@ -41,17 +40,15 @@ - [Export Route TCX](#export-route-tcx) - [Get Route](#get-route) - [List Athlete Routes](#list-athlete-routes) - [Running Races](#running-races) - [Get Running Race](#get-running-race) - - [List Running Races](#list-running-races) - [Segment Efforts](#segment-efforts) - [List Segment Efforts](#list-segment-efforts) - [Get Segment Effort](#get-segment-effort) - [Segments](#segments) - [Explore Segments](#explore-segments) - - [Get Segment Leaderboard](#get-segment-leaderboard) - [List Starred Segments](#list-starred-segments) - [Get Segment](#get-segment) - [Star Segment](#star-segment) - [Streams](#streams) - [Get Activity Streams](#get-activity-streams) @@ -64,10 +61,11 @@ - [OAuth](#oauth) - [OAuth Workflow](#oauth-workflow) - [Deauthorize](#deauthorize) - [Command Line OAuth Workflow](#command-line-oauth-workflow) - [Webhooks](#webhooks) + - [Ratelimit](#ratelimit) - [Configuration](#configuration) - [Web Client Options](#web-client-options) - [API Client Options](#api-client-options) - [OAuth Client Options](#oauth-client-options) - [Webhooks Client Options](#webhooks-client-options) @@ -107,11 +105,11 @@ Creates a manual activity for an athlete. ```ruby activity = client.create_activity( name: 'Afternoon Run', - type: 'Run', + sport_type: 'Run', start_date_local: Time.now, elapsed_time: 1234, # in seconds description: 'Test run.', distance: 1000 # in meters ) @@ -215,11 +213,10 @@ lap.name # => 'Lap 1' ``` See [Strava::Models::Lap](lib/strava/models/lap.rb) for all available properties. - #### List Athlete Activities Returns the currently logged-in athlete's activities. ```ruby @@ -228,10 +225,11 @@ activity = activities.first # => Strava::Models::Activity activity.name # => 'NYC TCS Marathon 2018' activity.strava_url # => 'https://www.strava.com/activities/1477353766' activity.type_emoji # => '🏃' +activity.sport_type_emoji # => '🏃' activity.distance_s # => '42.2km' activity.moving_time_in_hours_s # => '3h38m5s' activity.elapsed_time_in_hours_s # => '3h42m13s' activity.pace_s # => '5m15s/km' activity.pace_per_mile_s # => '8m28s/mi' @@ -270,11 +268,11 @@ ```ruby activity = client.update_activity( id: 1982980795, name: 'Afternoon Run (Updated)', - type: 'Run', + sport_type: 'Run', description: 'It was cold.' ) activity.name # => 'Afternoon Run (Updated)' activity.strava_url # => 'https://www.strava.com/activities/1982980795' @@ -528,27 +526,10 @@ running_race.website_url # => 'https://www.rundisney.com/disneyworld-marathon/' ``` See [Strava::Models::RunningRace](lib/strava/models/running_race.rb) for all available properties. -#### List Running Races - -Returns a list running races based on a set of search criteria. - -```ruby -running_races = client.running_races - -running_race = running_races.first # => Strava::Models::RunningRace - -running_race.name # => 'Walt Disney World Half Marathon' -running_race.distance # => 21_097.0 -running_race.measurement_preference # => 'feet' -running_race.distance_s # => '13.11mi' -``` - -See [Strava::Models::RunningRace](lib/strava/models/running_race.rb) for all available properties. - ### Segment Efforts #### List Segment Efforts Returns a set of the authenticated athlete's segment efforts for a given segment. @@ -614,41 +595,10 @@ segment.elev_difference # => 9.6 ``` See [Strava::Models::ExplorerSegment](lib/strava/models/explorer_segment.rb) for all available properties. -#### Get Segment Leaderboard - -Returns the specified segment leaderboard. - -```ruby -segment_leaderboard = client.segment_leaderboard(1109718) # => Strava::Models::SegmentLeaderboard - -segment_leaderboard.effort_count # => 204 -segment_leaderboard.entry_count # => 204 -segment_leaderboard.kom_type # => 'kom' -segment_leaderboard.entries # => Enumerable - -entry = segment_leaderboard.entries.first # => Strava::Models::SegmentLeaderboardEntry -entry.athlete_name # => 'Etan B.' -entry.moving_time_in_hours_s # => '1m32s' -entry.start_date # => Time -entry.start_date_local # => Time -entry.rank # => 1 -``` - -This API supports pagination through the entire segment leaderboard but wraps entries into a [Strava::Models::SegmentLeaderboard](lib/strava/models/segment_leaderboard.rb) object. - -```ruby -client.segment_leaderboard(1109718) do |row| - row # => Strava::Models::SegmentLeaderboard - row.entries # => Array[Strava::Models::SegmentLeaderboardEntry] -end -``` - -See [Strava::Models::SegmentLeaderboard](lib/strava/models/segment_leaderboard.rb) and [Strava::Models::SegmentLeaderboardEntry](lib/strava/models/segment_leaderboard_entry.rb) for all available properties. - #### List Starred Segments List of the authenticated athlete's starred segments. ```ruby @@ -896,11 +846,11 @@ event # => Strava::Webhooks::Models::Event event.object_type # => 'activity' event.object_id # => 1991813808 event.aspect_type # => 'update' -event.updates # => { 'type' => 'Walk' } +event.updates # => { 'sport_type' => 'Walk' } event.owner_id # => 29323238 event.subscription_id # => 131302 event.event_time # => DateTime ``` @@ -943,10 +893,62 @@ ```ruby client.delete_push_subscription(131300) # => nil ``` +### Ratelimit + +Every API call's HTTP Reponse Content, be it a single Model or a list (via pagination), can be accessed by using `#http_response`. + +`client.athlete` #=> `Strava::Models::Athlete#http_response` + +`client.activity_comments(id: 1234567)` #=> `Array<Strava::Models::Comment>#http_response` + +`http_response` itself is a `Strava::Web::ApiResponse` class. Ratelimits are accessed via this class using `Strava::Web::ApiResponse#ratelimit`. See the examples given below: + +```ruby +comments = client.activity_comments(id: 123_456_789) + +# comments == Array<Strava::Models::Comment> +comments.http_response.ratelimit.to_h +``` + +```ruby +athlete = client.athlete # => Strava::Models::Athlete +athlete.http_response.ratelimit +``` + +The following properties are available on Strava::Api::Ratelimit. + +- `limit` +- `limit?` +- `usage` +- `fifteen_minutes` +- `fifteen_minutes_usage` +- `fifteen_minutes_remaining` +- `total_day` +- `total_day_usage` +- `total_day_remaining` +- `to_h` +- `to_s` + +You can access the Hash containing all limits by calling `to_h`. + +```ruby +# athlete.http_response.ratelimit.to_h +{ + limit: limit, + usage: usage, + total_day: total_day, + total_day_usage: total_day_usage, + total_day_remaining: total_day_remaining, + fifteen_minutes: fifteen_minutes, + fifteen_minutes_usage: fifteen_minutes_usage, + fifteen_minutes_remaining: fifteen_minutes_remaining +} +``` + ## Configuration ### Web Client Options You can configure web client options used in the OAuth and API clients, globally. @@ -957,19 +959,19 @@ end ``` The following settings are supported. -setting | description ---------------------|------------ -user_agent | User-agent, defaults to _Strava Ruby Client/version_. -proxy | Optional HTTP proxy. -ca_path | Optional SSL certificates path. -ca_file | Optional SSL certificates file. -logger | Optional `Logger` instance that logs HTTP requests. -timeout | Optional open/read timeout in seconds. -open_timeout | Optional connection open timeout in seconds. +| setting | description | +| ------------ | ----------------------------------------------------- | +| user_agent | User-agent, defaults to _Strava Ruby Client/version_. | +| proxy | Optional HTTP proxy. | +| ca_path | Optional SSL certificates path. | +| ca_file | Optional SSL certificates file. | +| logger | Optional `Logger` instance that logs HTTP requests. | +| timeout | Optional open/read timeout in seconds. | +| open_timeout | Optional connection open timeout in seconds. | ### API Client Options The API client inherits web client options and provides additional application configuration. These can be configured globally or for a client instance. @@ -986,14 +988,14 @@ ) ``` The following settings are supported. -setting | description ---------------------|------------ -access_token | Access token to pass in the `Authorization` header. -endpoint | Defaults to `https://www.strava.com/api/v3`. +| setting | description | +| ------------ | --------------------------------------------------- | +| access_token | Access token to pass in the `Authorization` header. | +| endpoint | Defaults to `https://www.strava.com/api/v3`. | ### OAuth Client Options The OAuth client inherits web client options and provides additional application configuration. These can be configured globally or for a client instance. @@ -1012,15 +1014,15 @@ ) ``` The following settings are supported. -setting | description ---------------------|------------ -client_id | Application client ID. -client_secret | Application client secret. -endpoint | Defaults to `https://www.strava.com/oauth`. +| setting | description | +| ------------- | ------------------------------------------- | +| client_id | Application client ID. | +| client_secret | Application client secret. | +| endpoint | Defaults to `https://www.strava.com/oauth`. | ### Webhooks Client Options The Webhooks client inherits web client options and provides additional application configuration. These can be configured globally or for a client instance. @@ -1039,15 +1041,15 @@ ) ``` The following settings are supported. -setting | description ---------------------|------------ -client_id | Application client ID. -client_secret | Application client secret. -endpoint | Defaults to `https://www.strava.com/api/v3`. +| setting | description | +| ------------- | -------------------------------------------- | +| client_id | Application client ID. | +| client_secret | Application client secret. | +| endpoint | Defaults to `https://www.strava.com/api/v3`. | ## Errors All errors that return HTTP codes 400-600 result in either `Faraday::ResourceNotFound`, `Faraday::ConnectionFailed` or [Strava::Errors::Fault](lib/strava/errors/fault.rb) exceptions. @@ -1068,25 +1070,25 @@ ### Strava OAuth Token Use [strava-oauth-token](bin/strava-oauth-token) to obtain a token from the command-line. This will open a new browser window, navigate to Strava, request the appropriate permissions, then handle OAuth in a local redirect. The token type, refresh token, access token and token expiration will be displayed in the browser. ```bash -$ STRAVA_CLIENT_ID=... STRAVA_CLIENT_SECRET=... strava-oauth-token +STRAVA_CLIENT_ID=... STRAVA_CLIENT_SECRET=... strava-oauth-token ``` ## Users -* [Slava: Strava integration with Slack](https://slava.playplay.io), [source](https://github.com/dblock/slack-strava). -* [Jekyll Blog at run.dblock.org](https://run.dblock.org), [source](https://github.com/dblock/run.dblock.org) -* [Secret Strava](https://steele.blue/secret-strava/), [source](https://github.com/mattdsteele/secret-strava) +- [Slava: Strava integration with Slack](https://slava.playplay.io), [source](https://github.com/dblock/slack-strava). +- [Jekyll Blog at run.dblock.org](https://run.dblock.org), [source](https://github.com/dblock/run.dblock.org) +- [Secret Strava](https://steele.blue/secret-strava/), [source](https://github.com/mattdsteele/secret-strava) ## Resources -* [Strava API Documentation](https://developers.strava.com) -* [Writing a New Strava API Ruby Client](https://code.dblock.org/2018/11/27/writing-a-new-strava-api-ruby-client.html) -* [Dealing with Strava API OAuth Token Migration](https://code.dblock.org/2018/11/17/dealing-with-strava-api-token-migration.html) -* [Auto-Publishing Strava Runs to Github Pages](https://code.dblock.org/2018/02/17/auto-publishing-strava-runs-to-github-pages.html) -* [Strava Command-Line Client](https://github.com/dblock/strava-ruby-cli) +- [Strava API Documentation](https://developers.strava.com) +- [Writing a New Strava API Ruby Client](https://code.dblock.org/2018/11/27/writing-a-new-strava-api-ruby-client.html) +- [Dealing with Strava API OAuth Token Migration](https://code.dblock.org/2018/11/17/dealing-with-strava-api-token-migration.html) +- [Auto-Publishing Strava Runs to Github Pages](https://code.dblock.org/2018/02/17/auto-publishing-strava-runs-to-github-pages.html) +- [Strava Command-Line Client](https://github.com/dblock/strava-ruby-cli) ## Upgrading See [UPGRADING](UPGRADING.md).