Skip to content

Commit d31a9e4

Browse files
JohnnyCrazyJohnnyCrazy
committed
Update online docs
1 parent 2a9b033 commit d31a9e4

26 files changed

Lines changed: 628 additions & 426 deletions

‎SpotifyAPI.Docs/docs/auth_introduction.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
id: auth_introduction
3+
title: Introduction
4+
---
5+
6+
Hello

‎SpotifyAPI.Docs/docs/configuration.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
id: configuration
3+
title: Configuration
4+
---
5+
6+
To configure the spotify client functionality, the `SpotifyClientConfig` class exists.
7+
8+
```csharp
9+
var config = SpotifyClientConfig.CreateDefault("YourAccessToken");
10+
var spotify = new SpotifyClient(config);
11+
12+
// is the same as
13+
14+
var spotify = new SpotifyClient("YourAccessToken");
15+
```
16+
17+
We won't cover every possible configuration in this part, head over to the specific guides for that:
18+
19+
* ...
20+
21+
## HTTPClient Notes
22+
23+
One important part of the configuration is the used HTTPClient. By default, every time when a `SpotifyClientConfig` is instantiated, a new `HTTPClient` is created in the background. For Web Applications which require a lot of different configs due to user based access tokens, it is **not** advised to create a new config from scratch with every HTTP call. Instead, a default (static) config should be used to create a new config with a new access token.
24+
25+
Consider the following HTTP Endpoint:
26+
27+
```csharp
28+
public HttpResult Get()
29+
{
30+
var config = SpotifyClientConfig.CreateDefault("YourAccessToken")
31+
var spotify = new SpotifyClient(config);
32+
}
33+
```
34+
35+
This creates a new `HTTPClient` every time a request is made, which can be quite bad for the performance. Instead we should use a base config and use `WithToken`:
36+
37+
```csharp
38+
// somewhere global/static
39+
public static SpotifyClientConfig DefaultConfig = SpotifyClientConfig.CreateDefault();
40+
41+
public HttpResult Get()
42+
{
43+
var config = DefaultConfig.WithToken("YourAccessToken");
44+
var spotify = new SpotifyClient(config);
45+
}
46+
```
47+
48+
This way, a single `HTTPClient` will be used. For a real world example, checkout the [ASP.NET Example](example_aspnet)

‎SpotifyAPI.Docs/docs/error_handling.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
id: error_handling
3+
title: Error Handling
4+
---
5+
6+
API calls can fail when input data is malformed or the server detects issues with the request. As an example, the following request obviously fails:
7+
8+
```csharp
9+
var track = await spotify.Tracks.Get("NotExistingTrackId");
10+
Console.WriteLine(track.Name);
11+
```
12+
13+
When a request fails an `APIException` is thrown. Specific errors may throw a child exception of `APIException`.
14+
15+
## APIException
16+
17+
A very general API error. The message is parsed from the API response JSON body and the response is available as public property.
18+
19+
```csharp
20+
try {
21+
var track = await spotify.Tracks.Get("NotExistingTrackId");
22+
} catch(APIException e) {
23+
// Prints: invalid id
24+
Console.WriteLine(e.Message);
25+
// Prints: BadRequest
26+
Console.WriteLine(e.Response?.StatusCode);
27+
}
28+
```
29+
30+
## APIUnauthorizedException
31+
32+
Provides the same properties as `APIException` and occurs, when the access token is expired or not provided. Notice that an access token has to be included in **every** request. Spotify does not allow unauthorized API access.
33+
34+
## APITooManyRequestsException
35+
36+
Provides the same properties as `APIException` and occurs, when too many requests has been sent by your application. It also provides the property `TimeSpan RetryAfter`, which maps to the received `Retry-After` Header.
37+
38+
```csharp
39+
try {
40+
// call it very often?
41+
var track = await spotify.Tracks.Get("1s6ux0lNiTziSrd7iUAADH");
42+
} catch(APITooManyRequestsException e) {
43+
// Prints: seconds to wait, often 1 or 2
44+
Console.WriteLine(e.RetryAfter);
45+
}
46+
```

‎SpotifyAPI.Docs/docs/getting_started.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,107 @@
22
id: getting_started
33
title: Getting Started
44
---
5+
6+
import InstallInstructions from '../src/install_instructions'
7+
8+
## Adding SpotifyAPI-NET to your project
9+
10+
The library can be added to your project via the following methods:
11+
12+
### Package Managers
13+
14+
<InstallInstructions />
15+
16+
### Add DLL Manually
17+
18+
You can also grab the latest compiled DLL from our [GitHub Releases Page](https://github.com/johnnycrazy/spotifyapi-net/releases). It can be added to your project via Visual Studio or directly in your `.csproj`:
19+
20+
```xml
21+
<ItemGroup>
22+
<Reference Include="SpotifyAPI.Web">
23+
<HintPath>..\Dlls\SpotifyAPI.Web.dll</HintPath>
24+
</Reference>
25+
</ItemGroup>
26+
```
27+
28+
### Compile Yourself
29+
30+
```sh
31+
git clone https://github.com/JohnnyCrazy/SpotifyAPI-NET.git
32+
cd SpotifyAPI-NET
33+
dotnet restore
34+
dotnet build
35+
36+
ls -la SpotifyAPI.Web/bin/Debug/netstandard2.1/SpotifyAPI.Web.dll
37+
```
38+
39+
## First API Calls
40+
41+
You're now ready to issue your first calls to the Spotify API, a small console example:
42+
43+
```csharp
44+
using System;
45+
using SpotifyAPI.Web;
46+
47+
class Program
48+
{
49+
static async Task Main()
50+
{
51+
var spotify = new SpotifyClient("YourAccessToken");
52+
53+
var track = await spotify.Tracks.Get("1s6ux0lNiTziSrd7iUAADH");
54+
Console.WriteLine(track.Name);
55+
}
56+
}
57+
```
58+
59+
:::tip
60+
Notice that the spotify api does not allow unauthorized API access. Wondering where you should get an access token from? For a quick test, head over to the [Spotify Developer Console](https://developer.spotify.com/console/get-album/) and generate an access token with the required scopes! For a permanent solution, head over to the [authentication guides](auth_introduction).
61+
62+
:::
63+
64+
There is no online documentation for every available API call, but XML inline docs are available:
65+
66+
* [UserProfile](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/IUserProfileClient.cs)
67+
* [Browse](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/IBrowseClient.cs)
68+
* [Shows](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/IShowsClient.cs)
69+
* [Playlists](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/IPlaylistsClient.cs)
70+
* [Search](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/ISearchClient.cs)
71+
* [Follow](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/IFollowClient.cs)
72+
* [Tracks](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/ITracksClient.cs)
73+
* [Player](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/IPlayerClient.cs)
74+
* [Albums](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/IAlbumsClient.cs)
75+
* [Artists](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/IArtistsClient.cs)
76+
* [Personalization](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/IPersonalizationClient.cs)
77+
* [Episodes](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/IEpisodesClient.cs)
78+
* [Library](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/ILibraryClient.cs)
79+
80+
All calls have the [Spotify Web API documentation reference](https://developer.spotify.com/documentation/web-api/reference-beta/) attached as a remark.
81+
82+
83+
## Query/Body Parameters
84+
85+
If an API endpoint has query or body parameters, a request model can be supplied to the method
86+
87+
```csharp
88+
// No optional or required query/body parameters
89+
// The track ID is part of the request path --> it's not treated as query/body parameter
90+
var track = await spotify.Tracks.Get("1s6ux0lNiTziSrd7iUAADH");
91+
92+
// Optional query/body parameter
93+
var track = await spotify.Tracks.Get("1s6ux0lNiTziSrd7iUAADH", new TrackRequest{
94+
Market = "DE"
95+
});
96+
97+
// Sometimes, query/body parameters are also required!
98+
var tracks = await spotify.Tracks.GetSeveral(new TracksRequest(new List<string> {
99+
"1s6ux0lNiTziSrd7iUAADH",
100+
"6YlOxoHWLjH6uVQvxUIUug"
101+
}));
102+
```
103+
104+
If a query/body parameter is required, it has to be supplied in the constructor of the request model. In the background, empty/null checks are also performed to make sure required parameters are not empty/null. If it is optional, it can be supplied as a property to the request model.
105+
106+
## Guides
107+
108+
All other relevant topics are covered in the "Guides" and [Authentication Guides](auth_introduction) section in the sidebar!

‎SpotifyAPI.Docs/docs/installation.md‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

0 commit comments

Comments
 (0)