services

The primary goal of restd is use of the file format. Any server endpoint that satisfies the one requirement of using restd files is a restd service regardless of the service's public-facing design or intention.

The remainder of this page outlines specific service functionality as both a staring guideline and as a definition of base restd services.

base service specification

service URI

There are no restrictions on a restd service URI. Any location addressable over HTTP is valid regardless of programming language.

resource argument

Base restd services determine which resource to use with the query parameter /. The value is a / followed by a restd file name minus any extension. For example, a client can access a restd file named games.restd with the argument /=/games.

get

Issuing GET on a restd service returns an array of the resources currently available.

["games"]

Issuing GET on a restd resource requests objects from that resource.

everything

Calling GET on a resource will return all objects in the resource as determined by the service.

my.svc?/=/games

The above example could return an array of game information owned by the person managing the games restd file.

just one

Adding /key to the end of the resource name requests the resource at the given key in the restd file. In the restd file, the key relates to the objects block offset. The key is zero-based.

my.svc?/=/games/2

This example will return the third game in the restd file.

query

Adding the q query argument to the GET request performs a case-insenitive, full-text search of the JSON of each stored object and returns an array of all matches.

Separate search tearms with spaces. Strings enclosed in double quotes are considered one search term. An object must contain all terms to be included in the result. This is similar but not identical to the q parameter in Google's Base Data API.

If you required a double quote character inside a quoted search term, use double double quotes.

status

A client can determine success or failure through the HTTP response status code. This table lists possible outcomes and the status code returned by each.

situation

status

client requested a full resource without key

zero or more objects were successfully returned

200 – ok

client requested a specific object by key

it was successfully returned

200 – ok

client queried for objects by passing a q argument

zero or more objects were successfully returned

200 – ok

request URI is not parsable as either a full resource, a specific item of a resource or a query

400 – bad request

client requested a full resource or an specific item of a resource

the resource file does not exist on the server

404 – not found

client requested a specific item of a resource

the key is greater than the largest index possible in the restd file

404 – not found

client requested a specific item of a resource

the resource object has been deleted

404 – not found

client requested a full resource or a specific item of a resource

the resource file exists but the server cannot open it

500 – internal error

client requested a full resource or a specific item of a resource

any error happens while reading the resource file

500 – internal error

client request contains a known feature from a different restd service type

response body

A request for a specific object by key returns that object alone, e.g., the response body begins with an open 'stash: {

A request for a full resource returns a JSON array of objects, e.g., the response body begins with a square bracket: [

restd services should extend the returned objects with a _restd property. The value is a JavaScript string that describes the specific object in the restd service. restd attempts to harness the more static nature of the web in that deleting one object will not change the public uri of any other object in a restd service. The side-effect of this design is that requesting all the data in a restd service will leave deleted objects out of the resulting JSON array. An object's restd key may not match its position in the resulting array.

examples

Some games, pretending that I bought one between these three but sold it.

If the client wishes to query for one or more objects, this pseduo-code will retrieve search for them. The parseQuery function will break the q argument passed via the URL into search terms. We need to temporarily replace two double-quotes with a marker. They will become single double-quote characters in the search term.

post

The POST verb inserts a new object into a restd resource. The request URI specifies only the restd resource. The request body contains the JSON for the new object. Service developers should ignore _restd properties supplied with objects, they are only intended as a response to GET requests.

my.svc?/=/games

Request body for a new game.

{"name":"Bit.Trip Runner","genre":"platform"}

The request type is application/json.

status

If successful, the restd service will return a 200 status code or an error as determined by the following table.

situation

status

client posted a new object to a resource

the new object was successfully inserted

200 – ok

request URI has parameters but none are parsable as a resource

400 – bad request

request URI contains a resource and a key

400 – bad request

client posted a new object to a resource

the resource file does not exist on the server

404 – not found

client posted a new object to a resource

the JSON for the new object is larger than the blockSize of the restd file

413 – too large

client posted a new object to a resource

the resource file exists but the server cannot open it

500 – internal error

client posted a new object to a resource

any error happens while reading or writing to the resource file

500 – internal error

response body

The response body for a successful insert is the restd link for the new item, i.e., a string containing the resource and key.

It does not not matter that no other games have a platform property. However, a search for just the word platform will return both games in the platform genre as well as any game that has a platform property.

access of restd resource file

The following pseudo-code describes the file access required for posting a new object to a restd resource. Error checking is not included, readHeader is defined above.

While editing a restd file in a service, we lock the service processes to allow only one edit at a time. However, we open the file in shared-read mode so get requests are still allowed. Operating systems can handle this.

When posting a new item to the end of the file, we have to rewrite the restd file footer.

put

The PUT verb updates an existing object in a restd resource. The request URI specifies the restd resource and key. The request body contains the JSON for the updated object. Service developers should ignore _restd properties supplied with objects, they are only intended as a response to GET requests.

The base service only permits updates on existing, non-deleted objects. Application developers may update objects with {} to remove the object but keep its key active keeping in mind that these empty objects will be returned on GET requests for the entire resource.

status

If successful, the restd service will return a 200 status code or an error as determined by the following table.

situation

status

client updated an existing object in a resource

the object was successfully updated

200 – ok

request URI does not contain a resource and a key

400 – bad request

client updated an existing object in a resource

the resource file does not exist on the server

404 – not found

client updated an existing object in a resource

the key references a location that either does not exist or points to a deleted object

404 – not found

client updated an existing object in a resource

the JSON for the new object is larger than the blockSize of the restd file

413 – too large

client updated an existing object in a resource

the resource file exists but the server cannot open it

500 – internal error

client updated an existing object in a resource

any error happens while reading or writing to the resource file

500 – internal error

response body

Responses to a PUT do not contain a response body.

examples

Update a game.

my.svc?/=/games/4
{"name":"Bit.Trip Fate","genre":"shooter"}

response: 200

Attempt to update a deleted game.

my.svc?/=/games/1
{"name":"Diablo II","genre":"hack and slash"}

response: 404

access of restd resource file

The following pseudo-code describes the file access required for updating an existing object in a restd resource. Error checking is not included, readHeader is defined above.

locking

Unlike other document-based data stores such as CouchDB, restd performs un-cached locking during updates. This makes it slower than true data servers but restd is designed for publishing smaller or read-only datasets, situations where locking can simplify storage & access and should not be too noticable.