Skip to content

Commit 6377dc7

Browse files
KatisticKatistic
authored
Add usage examples (#19)
* Login example source * Use of API sections source * Use of No-Auth Requests source * Create getting-started examples readme * Update Getting-Started code Add our User-Agent * Update examples link * Remove duplicate line
1 parent 1ab966c commit 6377dc7

File tree

5 files changed

+226
-1
lines changed

5 files changed

+226
-1
lines changed

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ configuration = vrchatapi.Configuration(
4343

4444
# Enter a context with an instance of the API client
4545
with vrchatapi.ApiClient(configuration) as api_client:
46+
# Set our User-Agent as per VRChat Usage Policy
47+
api_client.user_agent = "MyProject/1.0 my@email.com"
4648

4749
# Instantiate instances of API classes
4850
auth_api = authentication_api.AuthenticationApi(api_client)
@@ -67,7 +69,7 @@ with vrchatapi.ApiClient(configuration) as api_client:
6769
print("Logged in as:", current_user.display_name)
6870
```
6971

70-
See [example.py](https://github.com/vrchatapi/vrchatapi-python/blob/main/example.py) for more example usage on getting started.
72+
See [Examples](https://github.com/vrchatapi/vrchatapi-python/blob/main/examples/README.md) for more example usage on getting started.
7173

7274
## Contributing
7375

‎examples/README.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
## Getting Started Examples
2+
3+
### Logging In
4+
5+
```Python
6+
# Step 1. We begin with creating a Configuration, which contains the username and password for authentication.
7+
import vrchatapi
8+
from vrchatapi.api import authentication_api
9+
from vrchatapi.exceptions import UnauthorizedException
10+
from vrchatapi.models.two_factor_auth_code import TwoFactorAuthCode
11+
from vrchatapi.models.two_factor_email_code import TwoFactorEmailCode
12+
13+
configuration = vrchatapi.Configuration(
14+
username = 'username',
15+
password = 'password',
16+
)
17+
18+
# Step 2. VRChat consists of several API's (WorldsApi, UsersApi, FilesApi, NotificationsApi, FriendsApi, etc...)
19+
# Here we enter a context of the API Client and instantiate the Authentication API which is required for logging in.
20+
21+
# Enter a context with an instance of the API client
22+
with vrchatapi.ApiClient(configuration) as api_client:
23+
# Set our User-Agent as per VRChat Usage Policy
24+
api_client.user_agent = "MyProject/1.0 my@email.com"
25+
26+
# Instantiate instances of API classes
27+
auth_api = authentication_api.AuthenticationApi(api_client)
28+
29+
try:
30+
# Step 3. Calling getCurrentUser on Authentication API logs you in if the user isn't already logged in.
31+
current_user = auth_api.get_current_user()
32+
except UnauthorizedException as e:
33+
if e.status == 200:
34+
if "Email 2 Factor Authentication" in e.reason:
35+
# Step 3.5. Calling email verify2fa if the account has 2FA disabled
36+
auth_api.verify2_fa_email_code(two_factor_email_code=TwoFactorEmailCode(input("Email 2FA Code: ")))
37+
elif "2 Factor Authentication" in e.reason:
38+
# Step 3.5. Calling verify2fa if the account has 2FA enabled
39+
auth_api.verify2_fa(two_factor_auth_code=TwoFactorAuthCode(input("2FA Code: ")))
40+
current_user = auth_api.get_current_user()
41+
else:
42+
print("Exception when calling API: %s\n", e)
43+
except vrchatapi.ApiException as e:
44+
print("Exception when calling API: %s\n", e)
45+
46+
print("Logged in as:", current_user.display_name)
47+
```
48+
49+
### Using The API
50+
51+
Okay, cool, we can log in, but what now?
52+
53+
The openapi generator splits each section of the API into it's own class. As such, we need to import each section of the API we want to use seperately. Expanding on our log-in example:
54+
55+
```Python
56+
import vrchatapi
57+
from vrchatapi.api import authentication_api
58+
from vrchatapi.exceptions import UnauthorizedException
59+
from vrchatapi.models.two_factor_auth_code import TwoFactorAuthCode
60+
from vrchatapi.models.two_factor_email_code import TwoFactorEmailCode
61+
62+
# We import the class that corrisponds to the section of the API we want to use
63+
from vrchatapi.api.worlds_api import WorldsApi
64+
65+
configuration = vrchatapi.Configuration(
66+
username = 'username',
67+
password = 'password',
68+
)
69+
70+
with vrchatapi.ApiClient(configuration) as api_client:
71+
api_client.user_agent = "MyProject/1.0 my@email.com"
72+
auth_api = authentication_api.AuthenticationApi(api_client)
73+
74+
try:
75+
current_user = auth_api.get_current_user()
76+
except UnauthorizedException as e:
77+
if e.status == 200:
78+
if "Email 2 Factor Authentication" in e.reason:
79+
auth_api.verify2_fa_email_code(two_factor_email_code=TwoFactorEmailCode(input("Email 2FA Code: ")))
80+
elif "2 Factor Authentication" in e.reason:
81+
auth_api.verify2_fa(two_factor_auth_code=TwoFactorAuthCode(input("2FA Code: ")))
82+
current_user = auth_api.get_current_user()
83+
else:
84+
print("Exception when calling API: %s\n", e)
85+
except vrchatapi.ApiException as e:
86+
print("Exception when calling API: %s\n", e)
87+
88+
print("Logged in as:", current_user.display_name)
89+
90+
# Now we are logged in, we can init and use the API class :)
91+
worlds_api = WorldsApi(api_client) # All API section classes require an ApiClient object to be passed!
92+
active_worlds = worlds_api.get_active_worlds()
93+
```
94+
95+
Here is a list of [all sections of the API:](https://github.com/vrchatapi/vrchatapi-python/tree/main/vrchatapi/api)
96+
- `authentication_api.AuthenticationApi`
97+
- `avatars_api.AvatarsApi`
98+
- `economy_api.EconomyApi`
99+
- `favorites_api.FavoritesApi`
100+
- `files_api.FilesApi`
101+
- `friends_api.FriendsApi`
102+
- `groups_api.GroupsApi`
103+
- `instances_api.InstancesApi`
104+
- `invite_api.InviteApi`
105+
- `notifications_api.NotificationsApi`
106+
- `permissions_api.PermissionsApi`
107+
- `playermoderation_api.PlayermoderationApi`
108+
- `system_api.SystemApi`
109+
- `users_api.UsersApi`
110+
- `worlds_api.WorldsApi`
111+
112+
### No Auth Requests
113+
114+
But some requests don't require Authentication, so how do we use them without logging in?
115+
116+
```Python
117+
import vrchatapi
118+
119+
# We import the class that corrisponds to the section of the API we want to use
120+
from vrchatapi.api.worlds_api import WorldsApi
121+
122+
# We don't add a configuration file/set a username and password
123+
with vrchatapi.ApiClient() as api_client:
124+
api_client.user_agent = "MyProject/1.0 my@email.com"
125+
126+
# We don't use the authentication API at all, since we don't need to
127+
world_api = WorldsApi(api_client)
128+
world = world_api.get_world("wrld_000000000-0000-0000-0000-000000000000")
129+
130+
print(f"World `{world.name}` was made by `{world.author_name}` ({world.author_id})")
131+
```

‎examples/examples-source/login.py‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Step 1. We begin with creating a Configuration, which contains the username and password for authentication.
2+
import vrchatapi
3+
from vrchatapi.api import authentication_api
4+
from vrchatapi.exceptions import UnauthorizedException
5+
from vrchatapi.models.two_factor_auth_code import TwoFactorAuthCode
6+
from vrchatapi.models.two_factor_email_code import TwoFactorEmailCode
7+
8+
configuration = vrchatapi.Configuration(
9+
username = 'username',
10+
password = 'password',
11+
)
12+
13+
# Step 2. VRChat consists of several API's (WorldsApi, UsersApi, FilesApi, NotificationsApi, FriendsApi, etc...)
14+
# Here we enter a context of the API Client and instantiate the Authentication API which is required for logging in.
15+
16+
# Enter a context with an instance of the API client
17+
with vrchatapi.ApiClient(configuration) as api_client:
18+
# Set our User-Agent as per VRChat Usage Policy
19+
api_client.user_agent = "MyProject/1.0 my@email.com"
20+
21+
# Instantiate instances of API classes
22+
auth_api = authentication_api.AuthenticationApi(api_client)
23+
24+
try:
25+
# Step 3. Calling getCurrentUser on Authentication API logs you in if the user isn't already logged in.
26+
current_user = auth_api.get_current_user()
27+
except UnauthorizedException as e:
28+
if e.status == 200:
29+
if "Email 2 Factor Authentication" in e.reason:
30+
# Step 3.5. Calling email verify2fa if the account has 2FA disabled
31+
auth_api.verify2_fa_email_code(two_factor_email_code=TwoFactorEmailCode(input("Email 2FA Code: ")))
32+
elif "2 Factor Authentication" in e.reason:
33+
# Step 3.5. Calling verify2fa if the account has 2FA enabled
34+
auth_api.verify2_fa(two_factor_auth_code=TwoFactorAuthCode(input("2FA Code: ")))
35+
current_user = auth_api.get_current_user()
36+
else:
37+
print("Exception when calling API: %s\n", e)
38+
except vrchatapi.ApiException as e:
39+
print("Exception when calling API: %s\n", e)
40+
41+
print("Logged in as:", current_user.display_name)

‎examples/examples-source/noauth.py‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
import vrchatapi
2+
3+
# We import the class that corrisponds to the section of the API we want to use
4+
from vrchatapi.api.worlds_api import WorldsApi
5+
6+
# We don't add a configuration file/set a username and password
7+
with vrchatapi.ApiClient() as api_client:
8+
api_client.user_agent = "MyProject/1.0 my@email.com"
9+
10+
# We don't use the authentication API at all, since we don't need to
11+
world_api = WorldsApi(api_client)
12+
world = world_api.get_world("wrld_000000000-0000-0000-0000-000000000000")
13+
14+
print(f"World `{world.name}` was made by `{world.author_name}` ({world.author_id})")

‎examples/examples-source/use_the_api.py‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
import vrchatapi
2+
from vrchatapi.api import authentication_api
3+
from vrchatapi.exceptions import UnauthorizedException
4+
from vrchatapi.models.two_factor_auth_code import TwoFactorAuthCode
5+
from vrchatapi.models.two_factor_email_code import TwoFactorEmailCode
6+
7+
# We import the class that corrisponds to the section of the API we want to use
8+
from vrchatapi.api.worlds_api import WorldsApi
9+
10+
configuration = vrchatapi.Configuration(
11+
username = 'username',
12+
password = 'password',
13+
)
14+
15+
with vrchatapi.ApiClient(configuration) as api_client:
16+
api_client.user_agent = "MyProject/1.0 my@email.com"
17+
auth_api = authentication_api.AuthenticationApi(api_client)
18+
19+
try:
20+
current_user = auth_api.get_current_user()
21+
except UnauthorizedException as e:
22+
if e.status == 200:
23+
if "Email 2 Factor Authentication" in e.reason:
24+
auth_api.verify2_fa_email_code(two_factor_email_code=TwoFactorEmailCode(input("Email 2FA Code: ")))
25+
elif "2 Factor Authentication" in e.reason:
26+
auth_api.verify2_fa(two_factor_auth_code=TwoFactorAuthCode(input("2FA Code: ")))
27+
current_user = auth_api.get_current_user()
28+
else:
29+
print("Exception when calling API: %s\n", e)
30+
except vrchatapi.ApiException as e:
31+
print("Exception when calling API: %s\n", e)
32+
33+
print("Logged in as:", current_user.display_name)
34+
35+
# Now we are logged in, we can init and use the API class :)
36+
worlds_api = WorldsApi(api_client) # All API section classes require an ApiClient object to be passed!
37+
active_worlds = worlds_api.get_active_worlds()

0 commit comments

Comments
 (0)