API - nesv/Scarlet GitHub Wiki

Introduction

As it developed, it turns out that it made the most sense for Scarlet to follow the CRUD way of doing things.

Reqeusts

This is the basic structure of a Scarlet URL:

http://127.0.0.1:6380/DB_NUM/KEY_NAME

For example, suppose we wanted to with with the foo key in database 0; our URL for that resource would be:

http://127.0.0.1:6380/0/foo

Responses

Scarlet responds to requests using a JSON-RPC-like structure, but wihout the id field, simply because it is not needed. These are the basic rules for parsing JSON responses from Scarlet:

  • There will always be two fields: result and error
  • When result is null, there is a message in the error field letting you know why the request failed

Now, because Redis has more that one, supported datatype for its keys, the following rules apply when reading keys:

  • Strings are left as-is 
    {"result": "Hello!", "error": null}
  • Lists, sets and ranked sets are converted to arrays 
    {"result": ["item1", "item2", ...], "error": null}
  • Hashes are converted to JSON objects 
    {"result": {"field1": "value1", ...}, "error": null}
  • Individual fields from a hash are converted to a string 
    {"result": "value1", "error": null}

Create

To create a new key, we are going to use the HTTP POST method. Regardless of what datatype we want the key to hold, our value is always provided through the ?value= parameter.

In this example, we are going to put a simple string into the scarlet.string key, on database #4:

$ curl http://localhost:6380/4/scarlet.string -d "value=Hello world"
{"error":null,"result":true}

But what if we want to use a different data type, like a list, or a hash?

Changing the key type

The container type of the key can only be set when you are creating the key; you can specify the key type through the ?type= parameter. The following example will create the some.key key, holding a list with the string "foobarbaz" as the first element:

$ curl http://localhost:6380/4/some.key -d value=foobarbaz -d type=list
{"error":null,"result":true}

The following types are available:

  • list — for lists
  • set — for sets
  • zset — for sorted sets
  • hash — for hashes
  • string (default, if ?type= is not specified)

NOTE

If you are not familiar with cURL, whenever you use the -d flag, cURL will automatically make your request using the HTTP POST method.

In the event you try to create a key that already exists, Scarlet will issue the following error:

{
    "error": "Key already exists.", 
    "result": null
}

Examples

Creating a string

$ curl localhost:6380/2/scarlet.string -d value=hello

Creating a set

$ curl localhost:6380/2/scarlet.set -d value=foo -d type=set

Creating a sorted set

When creating (or modifying) a sorted set, you should always provide the ?ranking= parameter. Any value to the ?ranking= parameter should be able to be coerced to a floating-point value. If a ranking is not specified, then a default value of 1.0 is used.

$ curl localhost:6380/2/scarlet.zset -d value=bar -d type=zset -d ranking=2.0

Creating a list

$ curl localhost:6380/2/scarlet.list -d value=baz -d type=list

Creating a hash

When creating, reading, or updating a hash, you will always have to supply the ?field= parameter.

$ curl localhost:6380/2/scarlet.hash -d field=quux -d value=narf -d type=hash

Read

Reading a resource is fairly straight-forward (especially if you remember the above key-to-result conversions):

$ curl http://localhost:6380/4/some.key
{"error":null,"result":["foobarbaz"]}

The following commands are used for the following types:

  • strings are fetched with GET
  • sets are fetched with SMEMBERS
  • sorted sets are retrieved with ZRANGE key 0 -1
  • lists are retrieved with LRANGE key 0 -1
  • hashes are fetched with HGETALL, but you can fetch a single field by providing the ?field=FIELD_NAME parameter which will invoke HGET

NOTE

Currently, the Redis driver being used by Scarlet does not support the use of the WITHSCORES argument to ZRANGE, but it is planned for the next minor release (0.7.0).

Update

Updating (or "modifying") a key can be done by the HTTP PUT method. Before modifying the key, Scarlet will get the type of the key and update/modify it according to the following rules:

  • strings are simply overwritten with the SET command
  • sets are appended to using the SADD command
  • sorted sets are added to by using the ZADD command
  • lists are extended by using the RPUSH command (more on LPUSHing, below)
  • hashes are added to by using the HSET command

In the event you try to update a key that does not exist, Scarlet will return the following error:

{
	"error": "Key does not exist, cannot update.",
	"result": null
}

Examples

Updating a string

$ curl -XPUT localhost:6380/2/scarlet.string -d "value=this is pretty neat"

Updating a set

$ curl -XPUT localhost:6380/2/scarlet.set -d "value=some value"

Updating a sorted set

By default, Scarlet will assuming a ranking of 1.0 for any additions to a sorted set. In the event you wish to give the value a different ranking, the same rule applies here as it does for creating sorted sets: the value provided to ?ranking= must be coercable to a floating-point value.

$ curl -XPUT localhost:6380/2/scarlet.zset -d value=golang -d ranking=100.0

Updating a list

$ curl -XPUT localhost:6380/2/scarlet.list -d value=citrus

Now, as mentioned above, updating a list uses the RPUSH command, but you can get Scarlet to prepend the value (add it to the left side of the list) by pspecifying the ?side= parameter with the value left, like so:

$ curl -XPUT localhost:6380/2/scarlet.list -d value=citrus -d side=left

Updating a hash

As when creating a hash, you must specify the ?field= parameter:

$ curl -XPUT localhost:6380/2/scarlet.hash -d field=author -d value=nesv

Delete

Deleting keys is extremely simple, and can be achieved using the HTTP DELETE method:

$ curl -XDELETE localhost:6380/2/some.key
{"error":null,"result":true}