shadertoy_api #

A Shadertoy client API definition for Dart

Introduction #

Provides a definition of the contracts and entities needed to create a Shadertoy dart client.

Three main types of contracts are defined in this library:

• A Client API, for the REST interfaces defined in the Shadertoy howto that 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 this type of client a API key should be obtained for a properly registered user on the apps page and the client implementation should support providing it at the time of the construction
• Extended Client API, provides access to the same methods as the previous API but adds methods namely users, playlists, shader comments and website media. Note that the shaders returned by this API should not be constrained by the public+api privacy settings.
• Store API, defines contracts supporting the creation of data stores thus providing a way to work offline with the downloaded shaders instead of hitting the client or extended client APIs. It supports all the methods as the previous API plus the storage primitives.

Capabilities #

This package provides a number of operations through two types of clients:

Client API

• Find shader by id
• Find shaders by a list of id's
• Query 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
• Find all shader ids
• Query 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 available on a extended API:

• Find user by id
• Query shaders by user id, 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
• Query shaders by user id, 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
• Find all shader ids by user id
• Find comments by shader id
• Find playlist by id.
• Query shaders by playlist id. All the query results are paginated through the from and num parameters
• Query shader ids by playlist id. All the query results are paginated through the from and num parameters

Store API

All the base and extended client API features plus the following:

• Find all user ids
• Find all users
• Save user
• Save users
• Delete user by id
• Find all shaders
• Save shader
• Save shaders
• Delete shader by id
• Find comment by id
• Find all comment ids
• Find all comments
• Save shader comments
• Find all playlist ids
• Find all playlists
• Save playlist
• Save playlist shaders
• Delete playlist by id

Getting Started #

Add this to your pubspec.yaml (or create it):

dependencies:
    shadertoy_api: ^1.0.21

Run the following command to install dependencies:

pub get

Finally, to start developing import the library:

import 'package:shadertoy_api/shadertoy_api.dart';

The following client and storage API implementations are available

Plugins	Status	Description
shadertoy_client		HTTP client to the Shadertoy REST and Site API
shadertoy_moor		A Moor storage implementation using the moor package

Usage #

Instantiate a ShadertoyClient implementation, for example the one provided by the package shadertoy_client, to access the client API:

final ws = newShadertoyWSClient('xx');

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:

var fsr = await ws.findShaderById('...');
if (fsr.ok) {
    print(fsr?.shader);
} else {
    print('Error: ${fsr.error.message}')
}

In alternative instantiate a ShadertoyExtendedClient implementation, for example the one provided by the package shadertoy_client, to access the Site API:

final site = newShadertoySiteClient();

and execute one of the methods provided, for example to obtain the shader comments by shader id execute findCommentsByShaderId providing the id of the shader as parameter:

final fsr = await site.findCommentsByShaderId('...');
if (fsr.ok) {
    fsr.comments.forEach((c)=> print(c.text));
} else {
    print('Error: ${fsr.error.message}')
}

To create a database providing the same set of read operations as the previous contracts but also the ability to save shaders as well as other entities a ShadertoyStore contract is also provided. The user should instantiate a ShadertoyStore providing the appropriate configurations for the implementation:

ShadertoyStore store = ...

and execute persistent operations, for example storing the definition of a shader in the store with:

var shader = Shader(...);
var ssr = await store.saveShader(shader);
if (ssr.ok) {
    print('Shader stored');
} else {
    print('Error: ${response.error.message}')
}

Model #

Contributing #

This a unofficial Shadertoy client library 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

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