shadertoy

Description:

shadertoy

shadertoy #






Overview #
The shadertoy library provides the support to interact with the Shadertoy site and REST API's defining the data model and contracts to query and store the shaders, comments, users, playlists and website media.
Features #

📌 REST API - Supports all the Shadertoy REST APIs (as defined here)
🌐 Site API - Supports scrapping of data directly from the Shadertoy site allowing the retrieval of users query comments, users, playlists and website media.
🔗 Hybrid API - Respects public+api privacy settings of the shaders while providing support for additional operations, namely the retrieval of shader comments, user, playlists and website media
➿ Extensible - Plug novel storage and client implementations reusing the APIs and entities defined on the shadertoy package

Client Implementations #
The following client implementations are available



Package
Pub
Description




shadertoy_client

HTTP client to the Shadertoy REST and Site API using the dio package



Storage Implementations #
The following storage implementations are available



Package
Pub
Description




shadertoy_sqlite

A Sqlite storage implementation using the drift package



Getting Started #
Select one of the client or storage implementations (or both) and add the package to your pubspec.yaml replacing x.x.x with the latest version of the implementation. The example below uses the shadertoy_client package which implements the shadertoy REST and site APIs:
dependencies:
shadertoy_client: ^x.x.x
copied to clipboard
Run the following command to install dependencies:
dart pub get
copied to clipboard
Finally, to start developing import the library:
import 'package:shadertoy_client/shadertoy_client.dart';
copied to clipboard
Usage #
Instantiate a ShadertoyClient implementation, for example the one provided by the package shadertoy_client to access the client API:
// Created a client to the REST API using the API key `apiKey`
final client = newShadertoyWSClient(apiKey);
copied to clipboard
and execute one of the methods provided, for example to obtain a shader by id execute the findShaderById method providing the id of the shader as parameter:
// Execute the call to the REST API
final result = await client.findShaderById('Mt3XW8');
// Check if there's errors
if (result.ok) {
// Print the shader name if not
print(fsr?.shader.name);
} else {
// Prints the error message otherwise
print('Error: ${result.error.message}')
}
copied to clipboard
In alternative instantiate a ShadertoyExtendedClient implementation, for example the one provided by the package shadertoy_client, to access the site API:
final client = newShadertoySiteClient();
copied to clipboard
and execute one of the methods provided, for example to obtain the shader comments by shader id execute the findCommentsByShaderId method providing the id of the shader as parameter:
// Execute the call to the site API
final result = await client.findCommentsByShaderId('MdX3Rr');
// Check if there's errors
if (result.ok) {
// Prints the shader comments
print(jsonEncode(result.comments));
} else {
// Prints the error message otherwise
print('Error: ${fsr.error.message}')
}
copied to clipboard
As mentioned in the feature list, to (optionally) respect the shader privacy constraints but still benefit from a larger set of operations (some of them available only through the site API), the hybrid API can be used. Start by instancianting a suitable hybrid API implementation, for example the one provided by the shadertoy_client package:
// Creates a hybrid client using the REST API key `apiKey`
// This effectivly filters the shaders and provides only the ones respecting the shader
// `public+api` privacy settings
final client = newShadertoyHybridClient(apiKey: apiKey);
copied to clipboard
and execute one of the methods provided, for example to obtain a shader by id execute findShaderById providing the id of the shader as parameter:
// Execute the call to the hybrid API
final result = await client.findShaderById('3lsSzf');
// Check if there's errors
if (result.ok) {
// Prints the shader id
print(result.shader?.info.id);
} else {
// Prints the error message otherwise
print('Error: ${result.error.message}')
}
copied to clipboard
To create a database providing the same set of read operations as the previous APIs but also the ability to save shaders as well as other entities a ShadertoyStore contract is also provided. To make use of the ShadertoyStore a suitable implementation should be provided, for example, the one available on shadertoy_sqlite:
// Creates a new store with an in-memory executor
final store = newShadertoySqliteStore(memoryExecutor());
copied to clipboard
and execute one of the operations, for example storing a user:
// Create a user
final user = User(id: 'UzZ0Z1', about: 'About user 1', memberSince: DateTime.now());
// Save the user
final result = await store.saveUser(user);
// Check if there's errors
if (result.ok) {
// Prints a success message
print('Shader stored');
} else {
// Prints the error message otherwise
print('Error: ${response.error.message}')
}
copied to clipboard
APIs #

The client API targetting the REST interfaces defined in the Shadertoy howto which allow the user to browse shaders available with public+api privacy settings. Note that the number of operations available with this API are limited albeit enough for simple browsing usage. To start using an API key needs to be obtained through a properly registered user on the apps page of the user section on the Shadertoy website.
The extended client API provides access to the same methods as the previous API but adds features that are only available on the site API, namely, the support to fetch users, playlists, shader comments and website media. Note that the shaders returned by this API are not constrained by the public+api privacy settings.
The hybrid API complements the basic client API allowing the base REST API client to benefit from the additional features os the extended client API still (optionally) respecting the public+api constrains imposed by the shader creators. In a nutshell it allows the REST API users to access user, shader comments and website media of the public+api shaders if configured with an API key
The store API, defines contracts supporting the creation of data stores thus providing a way to work offline with the downloaded shaders instead of relying on the Shadertoy APIs. It supports all the methods as the previous API plus the storage primitives.

Client API #



Operation
Description




findShaderById
Finds a shader by id


findShadersByIdSet
Finds shaders by a set of ids


findShaders
Queries shaders by term, tags and sort them by name, likes, views, newness and by hotness (proportional to popularity and inversely proportional to lifetime). All the query results are paginated through the from and num parameters


findAllShaderIds
Fetches all the shader ids


findShaderIds
Queries shader ids by term, tags and sort them by name, likes, views, newness and by hotness (proportional to popularity and inversely proportional to lifetime). All the query results are paginated through the from and num parameters



Extended Client API #
All the client API features plus the following:



Operation
Description




findUserById
Finds a Shadertoy user by id


findShadersByUserId
Queries shaders by user id, tags and allows sorting by name, likes, views, newness and hotness (proportional to popularity and inversely proportional to lifetime). All the query results are paginated and the pages fetched with the from and num parameters


findShaderIdsByUserId
Queries shader ids by user id, tags and allows sorting by name, likes, views, newness and hotness (proportional to popularity and inversely proportional to lifetime). All the query results are paginated and the pages fetched with the from and num parameters


findAllShaderIdsByUserId
Fetches all the shader ids by user id


findCommentsByShaderId
Fetches the comments of a shader id


findPlaylistById
Fetches a playlist by id


findShadersByPlaylistId
Fetches the shaders of a playlist id. All the query results are paginated through the from and num parameters


findShaderIdsByPlaylistId
Fetches the shader ids of a playlist id. All the query results are paginated through the from and num parameters


findShaderIdsByPlaylistId
Fetches all the shader ids of a playlist id



Hybrid Client #
All the client and extendec client features but optionally constraining the requests to shaders with public+api privacy settings.
Store API #
All the base and extended client API features plus the following:



Operation
Description




findAllUserIds
Returns all the stored user ids


findAllUsers
Returns all the stored users


saveUser
Saves a user


saveUsers
Saves a list of users


deleteUserById
Deletes a user by id


findAllShaders
Fetches all the shaders


saveShader
Saves a shader


saveShaders
Saves a list of shaders


deleteShaderById
Deletes a shader by id


findCommentById
Fetches a comment by id


findAllCommentIds
Returns all the comment ids


findAllComments
Returns all the comments


saveShaderComments
Saves a list of shader comments


deleteCommentById
Deletes a comment by id


savePlaylist
Saves a playlist


savePlaylistShaders
Associates a list of shader ids to a playlist


deletePlaylistById
Deletes a playlist by id


findAllPlaylistIds
Returns all the playlist ids


findAllPlaylists
Returns all the playlists



Model #

Contributing #
This is a unofficial Shadertoy client API. It is developed by best effort, in the motto of "Scratch your own itch!", meaning APIs that are meaningful for the author use cases.
If you would like to contribute with other parts of the API, feel free to make a Github pull request as I'm always looking for contributions for:

Tests
Documentation
New APIs

See CONTRIBUTING.md for ways to get started.
Features and Bugs #
Please file feature requests and bugs at the issue tracker.
License #
This project is licensed under the MIT License - see the LICENSE file for details