# Syncano 4.0 ruby gem ## Installation Using gems: ```bash $ gem install syncano --pre ``` ## First steps After installation, you have to set a path for api root for syncano. If you want to use staging, export: ```bash $ export API_ROOT=https://v4.hydraengine.com ``` If you're less adventurous, use our production api servers: ```bash $ export=API_ROOT=https://api.syncano.io ``` Ok, now we can start coding! ```ruby require 'syncano' syncano = Syncano.connect(api_key: 'your-api-key') syncano.instances.all.each { |instance| puts instance } ``` You can either pass your API key to the connect method as above or set `ENV['SYNCANO_API_KEY']` and call just `Syncano.connect`. ## API basics Syncano API is a nested API - all the endpointes are scoped by an instances, ex. codeboxes path is `/instance/your_instance_name/codeboxes/`. Syncano instances is more less a schema is in relation databases. **Your instance name must be unique across all existing Syncano instnaces, not only limitted to your account.** # Instances In order to do anything with Syncano, you have to create an instances. Choose a globally unique name and call: ```ruby instances = syncano.instances.create name: 'my_instances_name' instance.first #=> # ``` # Classes and objects In order to save objects in Syncano, first you need to create a class. A class defines objects' attributes in the class' schema. The attribute definition has two mandatory (`name`, `type`) and two optional fields (`filter_index`, `order_index`). What these fields are for is rather obvious - `name` defines objects' attribute name, and `type` defines type (you can read more about available types in the [API docs](http://docs.syncano.com/v0.1/docs/instancesinstanceclasses-2)). `*_index` fields are indexing. `order_index` allows you order returned collections, `filter_index` allows filtering in a various ways. There will be a few examples in this README, but you can read in the [API docs](http://docs.syncano.com/v0.1/docs/filtering-data-objects). ```ruby stock = instance.classes.create name: 'stock_items', schema: [{ name: 'name', type: 'string', filter_index: true }, { name: 'amount', type: 'integer', filter_index: true, order_index: true }] ``` Once we have a class, we can start creating objects. ```ruby chorizo = stock.objects.create name: 'Chorizo', amount: 100 black_pudding = stock.objects.create name: 'Black pudding', amount: 200 curry_wurts = stock.objects.create name: 'Curry wurst', amount: 150 kabanos = stock.objects.create name: 'Kabanos' something = stock.objects.create amount: 3 ``` Now we have a few items in stock, let's try filtering. ```ruby stock.objects.all(order_by: '-amount', query: { amount: { _lte: 150 }, name: { _exists: true } }) #=> #, #]> ``` Let's give `something` a name and try again. ```ruby something.name = 'Unidentified sausage' something.save stock.objects.all(order_by: '-amount', query: { amount: { _lte: 150 }, name: { _exists: true } }) #=> #, #, #]> ``` Now it matches the query and appears in the result. # Codeboxes Codeboxes are small pieces of code that run on Syncano servers. You can run them manually using the API, you can create a schedule to run them periodically, you can create a Webhook (and optionally make it public) to run them from the web, you can create a trigger to run one after a class' object is created, updated or deleted. There are three runtimes available: Ruby, Python and Node. This gem is available in Ruby runtime (just needs to be required). ## Contributing 1. Fork it 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create a new Pull Request