Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ivoleitao/shadertoy_api
A Shadertoy API client definition for Dart compatible with all platforms
https://github.com/ivoleitao/shadertoy_api
dart dartlang flutter shadertoy
Last synced: 3 months ago
JSON representation
A Shadertoy API client definition for Dart compatible with all platforms
- Host: GitHub
- URL: https://github.com/ivoleitao/shadertoy_api
- Owner: ivoleitao
- License: mit
- Archived: true
- Created: 2019-11-23T14:32:03.000Z (about 5 years ago)
- Default Branch: develop
- Last Pushed: 2021-04-10T23:58:39.000Z (almost 4 years ago)
- Last Synced: 2023-07-27T19:21:42.556Z (over 1 year ago)
- Topics: dart, dartlang, flutter, shadertoy
- Language: Dart
- Homepage:
- Size: 392 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# shadertoy_api
A Shadertoy client API definition for Dart
[](https://pub.dartlang.org/packages/shadertoy_api)
[](https://github.com/ivoleitao/shadertoy_api/actions)
[](https://codecov.io/gh/ivoleitao/shadertoy_api)
[](https://www.dartdocs.org/documentation/shadertoy_api/latest)
[](https://opensource.org/licenses/MIT)
## 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](https://www.shadertoy.com/howto#q2) 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](https://www.shadertoy.com/myapps) 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):
```dart
dependencies:
shadertoy_api: ^1.0.22
```
Run the following command to install dependencies:
```dart
pub get
```
Finally, to start developing import the library:
```dart
import 'package:shadertoy_api/shadertoy_api.dart';
```
The following client and storage API implementations are available
| Plugins | Status | Description |
| ---------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| [shadertoy_client](https://github.com/ivoleitao/shadertoy_client) | [](https://pub.dartlang.org/packages/shadertoy_client) | HTTP client to the Shadertoy REST and Site API |
| [shadertoy_moor](https://github.com/ivoleitao/shadertoy_moor) | [](https://pub.dartlang.org/packages/shadertoy_moor) | A Moor storage implementation using the [moor](https://pub.dev/packages/moor) package |
## Usage
Instantiate a `ShadertoyClient` implementation, for example the one provided by the package [shadertoy_client](https://pub.dev/packages/shadertoy_client), to access the client API:
```dart
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:
```dart
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](https://pub.dev/packages/shadertoy_client), to access the Site API:
```dart
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:
```dart
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:
```dart
ShadertoyStore store = ...
```
and execute persistent operations, for example storing the definition of a shader in the store with:
```dart
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](https://www.shadertoy.com) 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](https://github.com/ivoleitao/shadertoy_api/pulls) 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][tracker].
[tracker]: https://github.com/ivoleitao/shadertoy_api/issues/new
## License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/ivoleitao/shadertoy_api/LICENSE) file for details