shadertoy_api 1.0.4

Main entities and contracts supported by the shadertoy REST and WEB APIs. Can be used to create shadertoy web or persistent clients.

shadertoy_api

A Shadertoy client API definition for Dart compatible with all platforms

Introduction

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

The contracts defined in this library allow the creation of clients to the:

• Shadertoy REST API, which as presented in the howto, provides a number of operations that allow the user to browse the shaders currently 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
• Shadertoy Site API, provides access to the same methods as the previous API but adds more data namely users, playlists, shader comments and website media. Not that The shaders returned by this API should are not constrained by the public+api privacy settings. With that said, the client implementation should support the usage of a suitable user and password providing sign in and out methods or, in alternative, anonymous access.

Finally, this library defines contracts supporting the creation of data stores thus providing a way to work offline with the downloaded shaders instead of hitting the REST or Site APIs

Capabilities

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

REST API

• Find shader by id
• Find shaders from 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.
• Find all shader ids
• Find shaders 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.

Site API

All the REST API features plus the following:

• Login
• Logout
• Find user by id
• Find shaders by user 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 as well.
• Find comments by shader id
• Find playlist by id.
• Query shaders by playlist id. All the query results are paginated.
• Query shader ids by playlist id. All the query results are paginated.
• Download preview, i.e. the the shader thumbnails
• Download media, any other media provided by the Shadertoy website

Store API

All the REST and Site API features except login, logout, download preview and download media plus the following:

• Save user
• Find account by id
• Query account by name, type and system
• Save account
• Save shader
• Save shader comments
• Save playlist

Getting Started

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

dependencies:
    shadertoy_api: ^1.0.4

Run the following command to install dependencies:

pub install

Optionally use the following command to run the tests:

pub run test

Finally, to start developing import the library:

import 'package:shadertoy_api/shadertoy_api.dart';

Usage

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

ShadertoyWS ws = ...

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 ShadertoySite implementation, for example the one provided by the package shadertoy_client, to access the Site API:

ShadertoySite site = ...

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:

var 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