Spotify.NET/SpotifyAPI.Docs/docs/pagination.md

77 lines
2.9 KiB
Markdown
Raw Normal View History

2020-05-13 17:25:42 +01:00
---
2020-05-19 16:33:29 +01:00
id: pagination
title: Pagination
2020-05-13 17:25:42 +01:00
---
When working with Spotify responses, you will often encounter the `Paging<T>` type.
2020-05-13 17:25:42 +01:00
> The offset-based paging object is a container for a set of objects. It contains a key called Items (whose value is an array of the requested objects) along with other keys like Previous, Next and Limit which can be useful in future calls.
2020-05-13 17:25:42 +01:00
It allows you to only receive a subset of all available data and dynamically check if more requests are required. The library supports `Paging<T>` responses in two ways:
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
## PaginateAll
2020-05-13 17:25:42 +01:00
`PaginateAll` will query all remaining elements based on a first page and return all of them in an `IList`. This method should not be used for huge amounts of pages (e.g `Search` Endpoint), since it stores every response in memory.
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
```csharp
// we need the first page
2020-06-03 16:44:13 +01:00
var page = await spotify.Playlists.CurrentUsers();
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
// allPages will include the first page retrived before
var allPages = await spotify.PaginateAll(page);
```
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
## Paginate
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
:::info .NET Standard >= 2.1 required
:::
2020-05-13 17:25:42 +01:00
`Paginate` is based on `IAsyncEnumerable` and streams pages instead of returning them all in one list. This allows it to break the fetching early and keep only 1 page in memory at a time. This method should always be preferred to `PaginateAll`.
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
```csharp
// we need the first page
2020-06-03 16:44:13 +01:00
var page = await spotify.Playlists.CurrentUsers();
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
await foreach(var item in spotify.Paginate(page))
{
Console.WriteLine(item.Name);
// you can use "break" here!
}
2020-05-13 17:25:42 +01:00
```
2020-06-03 16:44:13 +01:00
Some endpoints have nested and/or multiple paginations objects. When requesting the next page, it will not return the actual paging object but rather the root level endpoint object. A good example is the `Search` endpoint, which contains up to 5 Paging objects. Requesting the next page of the nested `Artists` paging object will return another `Search` response, instead of just `Artists`. You will need to supply a mapper function to the `Paginate` call, which returns the correct paging object:
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
```csharp
var search = await spotify.Search.Item(new SearchRequest(
SearchRequest.Types.All, "Jake"
));
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
await foreach(var item in spotify.Paginate(search.Albums, (s) => s.Albums))
{
Console.WriteLine(item.Name);
// you can use "break" here!
2020-05-13 17:25:42 +01:00
}
```
2020-06-03 16:44:13 +01:00
## Paginators
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
Via the interface [`IPaginator`](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/Interfaces/IPaginator.cs), it can be configured how pages are fetched. It can be configured on a global level:
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
```csharp
var config = SpotifyClientConfig
.CreateDefault()
.WithPaginator(new YourCustomPaginator());
```
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
or on method level:
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
```csharp
await foreach(var item in spotify.Paginate(page, new YourCustomPaginator()))
{
Console.WriteLine(item.Name);
// you can use "break" here!
}
```
2020-05-13 17:25:42 +01:00
2020-06-03 16:44:13 +01:00
By default, [`SimplePaginator`](https://github.com/JohnnyCrazy/SpotifyAPI-NET/blob/master/SpotifyAPI.Web/Clients/SimplePaginator.cs) is used. It fetches pages without any delay.