API Documentation
Create object to wrap all API calls for lifter_api
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
url |
str | None
|
API endpoint base URL. Defaults to |
None
|
version |
str | None
|
Version of the API. Defaults to "v1", which is set to |
VERSION
|
auth_token |
str | None
|
Authorization token to access 'higher' methods. Defaults to None. |
None
|
Examples:
Importing:
>>> from lifter_api import LifterAPI
No credentials:
>>> api = LifterAPI()
With credentials (recommended):
>>> import os
>>> api = LifterAPI(auth_token=os.getenv("API_TOKEN"))
Different version and URL for api (not recommended):
>>> api = LifterAPI(url="https://otherurl.com", version="v2")
athletes(page=1)
List all athletes.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
page |
Optional[int]
|
The page number if there is pagination. Defaults to page 1. |
1
|
Returns:
Name | Type | Description |
---|---|---|
AthleteList |
AthleteList
|
List of athletes as well as page information. |
Examples:
Typical use:
>>> api.athletes()
{
"count": 100,
"next": "https://nexturlpage"
"prev": null
"ressults": [
"athletes"
]
}
Specifying a page:
>>> api.athletes(page=2)
find_athlete(search, page=1, ordering='last_name', ascending=True)
Search for an athlete.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
search |
str
|
Search term for athlete; this will be the athlete's name. |
required |
page |
int
|
Page number for search. Defaults to 1. |
1
|
ordering |
str
|
Accepts |
'last_name'
|
ascending |
bool
|
If the search results are ascending or descending, defaults to True. |
True
|
Raises:
Type | Description |
---|---|
NotAllowedError
|
The ordering was inputted incorrectly. |
Returns:
Name | Type | Description |
---|---|---|
AthleteList |
AthleteList
|
Search results of athletes as well as page information. |
Examples:
Typical use:
>>> api.find_athlete("Athlete")
# TODO: output
Customising search:
>>> api.find_athlete(search="Athlete", page=2, order="first_name",
ascending=False)
# TODO output
get_athlete(athlete_id)
Get information about an athlete.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
athlete_id |
str
|
Athlete ID. |
required |
Returns:
Type | Description |
---|---|
AthleteDetail | DetailResponse
|
Athlete details including lifts in competitions. |
Examples:
Typical use:
>>> athlete_id = 'ab345l' # Hashid
>>> api.get_athlete(athlete_id=athlete_id)
# TODO: output
create_athlete(first_name, last_name, yearborn)
Create an athlete.
NB: Duplicate athlete names can be created, so it might be a wise to utilise lifter_api.LifterAPI.find_athlete
to search for the athlete first and then determine whether or not you want to create a new athlete. This might be written in the future.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
first_name |
str
|
First name of athlete and can include middle names. |
required |
last_name |
str
|
Surname of athlete. |
required |
yearborn |
int
|
Birth year. |
required |
Returns:
Name | Type | Description |
---|---|---|
AthleteDetail |
AthleteDetail
|
information about created athlete. |
Examples:
Typical use:
>>> api.create_athlete(
first_name="Example",
last_name="Athlete",
yearborn=1990
date_start="2020-01-01"
)
# TODO: output
A handy tip is to unpack dictionaries:
>>> athlete = {
"first_name": "Example",
"last_name": "Athlete",
"yearborn": 1990,
}
>>> api.create_athlete(**athlete)
edit_athlete(athlete_id, **kwargs)
Edit an existing athlete.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
athlete_id |
str
|
Athlete ID. |
required |
**kwargs |
first_name (str), last_name(str), yearborn (int). |
{}
|
Returns:
Type | Description |
---|---|
AthleteDetail | DetailResponse
|
AthleteDetail | DetailResponse: Information about edited athlete. |
Examples:
Typical use:
>>> api.edit_athlete(athlete_id="123def7", last_name="Athlete")
# TODO: output
delete_athlete(athlete_id)
Delete an existing athlete.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
athlete_id |
str
|
Athlete ID. |
required |
Returns:
Name | Type | Description |
---|---|---|
DetailResponse |
DetailResponse
|
Information about deleted athlete. Will also return if athlete does not exist. |
Examples:
Typical use:
>>> api.delete_athlete(athlete_id="123def7")
{ "detail": Athlete ID: '123def7' deleted. }
competitions(page=1)
List all competitions.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
page |
int
|
Page number if there is pagination. Defaults to 1. |
1
|
Returns:
Name | Type | Description |
---|---|---|
CompetitionList |
CompetitionList
|
List of competition. Also, there will be pagination information. |
Examples:
Typical use:
>>> api.competitions()
# TODO: output
Getting specific page:
>>> api.competitions(page=2)
# TODO: output
get_competition(competition_id)
Get detail of an existing competition and it also includes the lifts.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
competition_id |
str
|
Competition ID. |
required |
Returns:
Type | Description |
---|---|
CompetitionDetail | DetailResponse
|
Data for the competition and lifts. |
Examples:
Typical use:
>>> competition_id = "1b3de7" # hashid
>>> api.get_competition(competition_id=competition_id)
# TODO: output
find_competition(search='', page=1, date_after='', date_before=None, order_by_date=False, ascending=False)
Find a competition by name, location search and/or by date.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
search |
str
|
Search parameter for location and/or name. Defaults to "" |
''
|
page |
int
|
Page of number for search. |
1
|
date_after |
str | datetime
|
Search after date. |
''
|
date_before |
str | datetime
|
Search before date. If left as |
None
|
order_by_date |
bool
|
To order by date. |
False
|
ascending |
bool
|
Ascending order for date search. |
False
|
Returns:
Type | Description |
---|---|
The competitions that have been found. |
Examples:
Typical use:
>>> api.find_competition(search="Competition")
# TODO: output
Customising search:
>>> api.find_competition(search="Competition", page=3,
date_start="2022-09-17")
# TODO: output
create_competition(date_start, date_end, location, name)
Create a competition.
NB: Competitions can be duplicated. There is no check for an existing competition. A good idea is to loop through all the competitions using lifter_api.LifterAPI.competitions
and search for competitions with a similar date or name. In the future, a check will be added to reduce the change of duplicated competition.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
date_start |
str
|
Start date of the competition. Format: YYYY-MM-DD. |
required |
date_end |
str
|
End date of the competition. Format: YYYY-MM-DD. |
required |
location |
str
|
Location of the competition. |
required |
name |
str
|
The name of the competition. |
required |
Returns:
Name | Type | Description |
---|---|---|
CompetitionDetail |
CompetitionDetail
|
Created competition information. |
Examples:
Typical use:
>>> api.create_competition(
date_start="2020-01-01",
date_end="2020-01-02",
location="Example Place",
name="Example Competition"
)
# TODO: output
A handy tip is to unpack dictionaries:
>>> competition = {
date_start: "2020-01-01",
date_end: "2020-01-02",
location: "Example Place",
name: "Example Competition"
}
>>> api.create_competition(**competition)
# TODO: output
edit_competition(competition_id, **kwargs)
Edit an existing competition.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
competition_id |
str
|
Competition ID. |
required |
**kwargs |
date_start (str), date_end (str), location (str), |
{}
|
Returns:
Type | Description |
---|---|
CompetitionDetail | DetailResponse
|
Return competition information. Will also return if competition does not exist. |
Examples:
>>> # TODO
delete_competition(competition_id)
Delete a competition.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
competition_id |
str
|
Competition ID. |
required |
Returns:
Name | Type | Description |
---|---|---|
DetailResponse |
DetailResponse
|
Returning information about deleted competition. Will also return if the competition does not exist. |
Examples:
Typical use:
>>> api.delete_competition(competition_id='ab345l')
{ "detail": "Competition_ID: 'ab345l' entry deleted."}
lifts(competition_id)
Provide lifts and competitions.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
competition_id |
str
|
Competition ID. |
required |
Raises:
Type | Description |
---|---|
NotAllowedError
|
Status Error. |
Returns:
Type | Description |
---|---|
list[LiftDetail] | DetailResponse
|
list[LiftDetail] | DetailResponse: Lift |
list[LiftDetail] | DetailResponse
|
data plus pagination information. Will also return if competition does not exist. |
Examples:
Typical use:
>>> competition_id = "ab345l" # hashid
>>> api.lifts(competition_id=competition_id)
# TODO: output
get_lift(competition_id, lift_id)
Get particular lift data.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
competition_id |
str
|
Competition ID |
required |
lift_id |
str
|
Lift ID |
required |
Returns:
Type | Description |
---|---|
LiftDetail | DetailResponse
|
Lift information. Will also return if competition does not exist. |
Examples:
Typical use:
>>> competition_id = "123def7" # hashid
>>> lift_id = "abc456l"
>>> api.get_lift(
competition_id=competition_id,
athlete_id=athlete_id
)
create_lift(competition_id, athlete_id, snatch_first, snatch_first_weight, snatch_second, snatch_second_weight, snatch_third, snatch_third_weight, cnj_first, cnj_first_weight, cnj_second, cnj_second_weight, cnj_third, cnj_third_weight, bodyweight, weight_category, session_number, team, lottery_number)
Create a lift in an existing session.
The API has internal validation to ensure that an athlete cannot have more than one lift object associated with a competition.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
competition_id |
str
|
Competition ID. |
required |
athlete_id |
str
|
Athlete ID. |
required |
snatch_first |
str
|
Accepts "LIFT", "NOLIFT", "DNA". |
required |
snatch_first_weight |
int
|
Weight of the lift. |
required |
snatch_second |
str
|
Same as snatch_first. |
required |
snatch_second_weight |
int
|
Weight must be same or larger if |
required |
snatch_third |
str
|
Same idea as snatch_first. |
required |
snatch_third_weight |
int
|
Same as snatch_second_weight. |
required |
cnj_first |
str
|
Follow same as snatches. |
required |
cnj_first_weight |
int
|
Follows as above. |
required |
cnj_second |
str
|
Follows as above. |
required |
cnj_second_weight |
int
|
Follows as above. |
required |
cnj_third |
str
|
Follows as above. |
required |
cnj_third_weight |
int
|
Follows as above. |
required |
bodyweight |
float
|
Body weight in kilograms. |
required |
weight_category |
str
|
Appropriate weight category. |
required |
session_number |
int
|
Session number. |
required |
team |
str
|
Team. |
required |
lottery_number |
int
|
Determines lift order. |
required |
Raises:
Type | Description |
---|---|
NotAllowedError
|
Status error. |
Returns:
Type | Description |
---|---|
LiftDetail | DetailResponse
|
LiftDetail | DetailResponse: Information about created lift. Will also return if athlete, session or competition does not exist. |
Examples:
Typical use:
>>> api.create_lift(
competition_id="123def7",
athlete_id="ab345l",
snatch_first="LIFT",
snatch_first_weight=90,
snatch_second="NOLIFT",
snatch_second_weight=95,
snatch_third="LIFT",
snatch_third_weight=95,
cnj_first="LIFT",
cnj_first_weight=120,
cnj_second="DNA",
cnj_second_weight=0,
cnj_third="DNA",
cnj_third_weight="DNA",
bodyweight=88.5,
weight_category="M89",
session_number=1,
team="TEAM",
lottery_number=1,
)
# TODO: output
A handy tip is to unpack dictionaries:
>>> lift = {
"competition_id": "123def7",
"athlete_id": "ab345l",
"snatch_first": "LIFT",
"snatch_first_weight": 90,
"snatch_second": "NOLIFT",
"snatch_second_weight": 95,
"snatch_third": "LIFT",
"snatch_third_weight": 95,
"cnj_first": "LIFT",
"cnj_first_weight": 120,
"cnj_second": "DNA",
"cnj_second_weight": 0,
"cnj_third": "DNA",
"cnj_third_weight": "DNA",
"bodyweight": 88.5,
"weight_category": "M89",
"session_number": 1,
"team": "TEAM",
"lottery_number": 1,
}
api.create_lift(**lift)
# TODO: output
edit_lift(competition_id, lift_id, **kwargs)
Edit an existing lift.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
competition_id |
str
|
competition id |
required |
lift_id |
str
|
lift id |
required |
Returns:
Type | Description |
---|---|
LiftDetail | DetailResponse
|
edited lift information and return messages if competition id is invalid. |
Examples:
>>> # TODO
delete_lift(competition_id, lift_id)
Delete an existing lift.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
competition_id |
str
|
Competition ID. |
required |
lift_id |
str
|
Lift ID. |
required |
Returns:
Name | Type | Description |
---|---|---|
DetailResponse |
DetailResponse
|
Information about deleted lift. Will also mention if session or competition does not exist. |
Examples:
>>> # TODO