From 14075128ece4b0a826c983f94383bd0e5d970abf Mon Sep 17 00:00:00 2001 From: Ritchie Date: Tue, 3 Apr 2012 10:56:33 -0700 Subject: [PATCH 1/2] updated doc styles --- docs/collection.html | 272 ++++++++++++++++++++++++++++++++++- docs/collection.markdown | 79 ++++------ docs/files.html | 55 +++++++ docs/files.markdown | 19 +++ docs/index.html | 73 +++++++++- docs/layout/header.html | 12 +- docs/static.html | 28 ---- docs/static.markdown | 23 --- docs/usercollection.html | 68 ++++++++- docs/usercollection.markdown | 13 +- 10 files changed, 526 insertions(+), 116 deletions(-) create mode 100644 docs/files.html create mode 100644 docs/files.markdown delete mode 100644 docs/static.html delete mode 100644 docs/static.markdown diff --git a/docs/collection.html b/docs/collection.html index 09856db..9f47a35 100644 --- a/docs/collection.html +++ b/docs/collection.html @@ -4,6 +4,7 @@ Deployd Documentation +
@@ -13,15 +14,280 @@ Deployd +
-
/bin/sh: markdown: command not found +

Collection Resource

+ +

A Collection resource allows your app to save and load data in a simple schema.

+ +

Setting up a collection

+ +

After creating a Collection resource in the dashboard, you can set up the schema by dragging properties into the database and naming them.

+ +

The grid view below the property list allows you to edit the Collection manually.

+ +

Property types

+ +

You can currently use the following property types:

+ +
    +
  • String - Arbritrary text data
    • +
  • Number - Numeric value, supports floating points
    • +
  • Boolean - True or false
    • +
  • Date - A specific point in time
    • +
+ +

Formats

+ +

You must format the request body as a JSON string and pass the header "Content-Type: application/json".

+ +

Saving data

+ +

To save data, send a POST request to the root of the Collection:

+ +
POST /people
+Content-Type: application/json
+{
+  "age": 23,
+  "firstName": "Joe",
+  "lastName": "Smith"
+}
+
+ +

The server will respond with the object, which will have a new _id property.

+ +
200 OK
+{
+  "_id": "4f71fc7c2ba744786f000001",
+  "age": 23,
+  "firstName": "Joe",
+  "lastName": "Smith"
+}
+
+ +

This _id is used to find the object's URL (i.e. /people/4f71fc7c2ba744786f000001)

+ +

Listing data

+ +

A GET request to the root of the Collection will return an array of objects in the collection:

+ +
GET /people
+
+200 OK
+[
+  {
+    "_id": "4f71fc7c2ba744786f000001",
+    "age": 23,
+    "firstName": "Joe",
+    "lastName": "Smith"
+  },
+  {
+    "_id": "4f71fe8b2ba744786f000002",
+    "age": 36,
+    "firstName": "John",
+    "lastName": "Doe"
+  }
+]
+
+ +

Retrieving a specific object

+ +

A GET request at an object's URL will return the properties of that object:

+ +
GET /people/4f71fc7c2ba744786f000001
+
+200 OK
+{
+  "_id": "4f71fc7c2ba744786f000001",
+  "age": 23,
+  "firstName": "Joe",
+  "lastName": "Smith"
+}
+
+ +

Updating an object

+ +

A PUT request at an object's URL will update the object. You must include all properties except for _id.

+ +
PUT /people/4f71fc7c2ba744786f000001
+Content-Type: application/json
+{
+  "age": 24,
+  "firstName": "Fred",
+  "lastName": "Smith"
+}
+
+ +

The server will respond with the entire object:

+ +
200 OK
+{
+  "_id": "4f71fc7c2ba744786f000001",
+  "age": 24,
+  "firstName": "Fred",
+  "lastName": "Smith"
+}
+
+ +

Deleting an object

+ +

A DELETE request at an object's URL will permanently remove that object from the collection:

+ +
DELETE /people/4f71fc7c2ba744786f000001
+
+204 No Content
+
+ +

Filtering results

+ +

You can add querystring parameters to a GET request at the root to filter the results by properties specified:

+ +
GET /people?firstName=Joe&lastName=Smith
+
+ +

NOTE: This currently only works for String properties.

+ +

Advanced querying

+ +

If you need to query additional types of properties, pass a JSON object as the q parameter with the properties you wish to filter:

+ +
GET /people?q={
+  "age": 23
+}
+
+ +

The q parameter supports MongoDB's query language for particularly advanced queries. Note that Collections do not currently support embedded documents or arrays.

+ +
GET /people?q={
+  "$orderby": { "age": 1 },
+  "name": {
+    "$regex": "^j"
+    "$options": "i",
+  }
+}
+
+ +

Collection Event Handlers

+ +

You can attach micro-scripts to events to add logic and validation to your objects. Collections currently support the following events:

+ +
    +
  • On Get - called when data is read
    • +
  • On Post - called when data is created
    • +
  • On Put - called when data is updated
    • +
  • On Delete - called when data is destroyed
    • +
+ +

Reading and setting properties

+ +

In an event micro-script, the this object refers to the current object, and has all of the properties of the object.

+ +

You can set values on the this object during an On Post or On Put event. These changes will be saved to the database.

+ +
// On Post:
+this.dateCreated = new Date();
+
+// On Put:
+this.totalScore = this.level1Points + this.level2Points;
+
+ +

Accessing the current user

+ +

If the request is coming from a logged in User, you can use the "me" object to access their properties.

+ +
// On Post:
+this.creator = me._id;
+
+ +

Cancelling an event

+ +

You can stop any event by calling the cancel(message, [code]) method.

+ +
//On Delete:
+if (this.protected) {
+  cancel('This post is protected and cannot be deleted');
+}
+
+DELETE /posts/123456
+
+400 Bad Request
+{
+  "message": "This post is protected and cannot be deleted"
+}
+
+ +

You can pass an integer to the cancel() method as the second parameter to set the HTTP status code. For example, 401 means "Unauthorized".

+ +
//On Put
+if (this.creator !== me._id) {
+  cancel("You cannot view this post because it is not yours!", 401);
+}
+
+PUT /posts/13456
+Content-Type: application/json
+{ ... }
+
+401 Unauthorized
+{
+  "message": "You cannot view this post because it is not yours!"
+}
+
+ +

Validation

+ +

Use the error(name, message) function to add a validation error.

+ +
//On Post
+if (this.age < 18) {
+  error('age', 'must be older than 18')
+}
+
+POST /people
+{
+  "firstName": "Joe",
+  "lastName": "Smith",
+  "age": 12
+}
+
+400 Bad Request
+{
+  errors: {
+    "age": "must be older than 18"
+  }
+}
+
+ +

Hiding properties

+ +

If you wish to hide certain properties from a user, use the hide(propertyName) function.

+ +
//On Get
+if (this.creator !== me._id) {
+  hide('lastName');
+  hide('age');
+}
+
+ +

Protecting properties from modification

+ +

Use the protect(propertyName) function to protect specified properties during a POST or PUT.

+ +
//On Put
+protect('createdDate');
+
diff --git a/docs/collection.markdown b/docs/collection.markdown index af9aaa6..976fb4f 100644 --- a/docs/collection.markdown +++ b/docs/collection.markdown @@ -1,17 +1,14 @@ -Collection Resource -=================== +# Collection Resource A Collection resource allows your app to save and load data in a simple schema. -Setting up a collection ------------------------ +## Setting up a collection After creating a Collection resource in the dashboard, you can set up the schema by dragging properties into the database and naming them. The grid view below the property list allows you to edit the Collection manually. -Property types --------------- +## Property types You can currently use the following property types: @@ -20,13 +17,11 @@ You can currently use the following property types: * **Boolean** - True or false * **Date** - A specific point in time -Formats -------- +## Formats You must format the request body as a JSON string and pass the header "Content-Type: application/json". -Saving data ------------ +## Saving data To save data, send a POST request to the root of the Collection: @@ -38,7 +33,7 @@ To save data, send a POST request to the root of the Collection: "lastName": "Smith" } -The server will respond with the object, which will have a new "_id" property. +The server will respond with the object, which will have a new `_id` property. 200 OK { @@ -48,10 +43,9 @@ The server will respond with the object, which will have a new "_id" property. "lastName": "Smith" } -This _id is used to find the object's URL (i.e. /people/4f71fc7c2ba744786f000001) +This `_id` is used to find the object's URL (i.e. `/people/4f71fc7c2ba744786f000001`) -Listing data ------------- +## Listing data A GET request to the root of the Collection will return an array of objects in the collection: @@ -73,8 +67,7 @@ A GET request to the root of the Collection will return an array of objects in t } ] -Retrieving a specific object ----------------------------- +## Retrieving a specific object A GET request at an object's URL will return the properties of that object: @@ -89,10 +82,9 @@ A GET request at an object's URL will return the properties of that object: } -Updating an object ------------------- +## Updating an object -A PUT request at an object's URL will update the object. You must include all properties except for "_id". +A PUT request at an object's URL will update the object. You must include all properties except for `_id`. PUT /people/4f71fc7c2ba744786f000001 Content-Type: application/json @@ -112,8 +104,8 @@ The server will respond with the entire object: "lastName": "Smith" } -Deleting an object ------------------- +## Deleting an object + A DELETE request at an object's URL will permanently remove that object from the collection: @@ -122,8 +114,7 @@ A DELETE request at an object's URL will permanently remove that object from the 204 No Content -Filtering results ------------------ +## Filtering results You can add querystring parameters to a GET request at the root to filter the results by properties specified: @@ -131,16 +122,15 @@ You can add querystring parameters to a GET request at the root to filter the re **NOTE**: This currently only works for String properties. -Advanced querying ------------------ +## Advanced querying -If you need to query additional types of properties, pass a JSON object as the "q" parameter with the properties you wish to filter: +If you need to query additional types of properties, pass a JSON object as the `q` parameter with the properties you wish to filter: GET /people?q={ "age": 23 } -The "q" parameter supports [MongoDB's query language](http://www.mongodb.org/display/DOCS/Advanced+Queries) for particularly advanced queries. Note that Collections do not currently support embedded documents or arrays. +The `q` parameter supports [MongoDB's query language](http://www.mongodb.org/display/DOCS/Advanced+Queries) for particularly advanced queries. Note that Collections do not currently support embedded documents or arrays. GET /people?q={ "$orderby": { "age": 1 }, @@ -151,8 +141,7 @@ The "q" parameter supports [MongoDB's query language](http://www.mongodb.org/dis } -Collection Event Handlers -========================= +# Collection Event Handlers You can attach micro-scripts to events to add logic and validation to your objects. Collections currently support the following events: @@ -161,12 +150,11 @@ You can attach micro-scripts to events to add logic and validation to your objec * **On Put** - called when data is updated * **On Delete** - called when data is destroyed -Reading and setting properties ------------------------------- +## Reading and setting properties -In an event micro-script, the "this" object refers to the current object, and has all of the properties of the object. +In an event micro-script, the `this` object refers to the current object, and has all of the properties of the object. -You can set values on the "this" object during an On Post or On Put event. These changes will be saved to the database. +You can set values on the `this` object during an On Post or On Put event. These changes will be saved to the database. // On Post: this.dateCreated = new Date(); @@ -174,8 +162,7 @@ You can set values on the "this" object during an On Post or On Put event. These // On Put: this.totalScore = this.level1Points + this.level2Points; -Accessing the current user --------------------------- +## Accessing the current user If the request is coming from a logged in User, you can use the "me" object to access their properties. @@ -183,10 +170,9 @@ If the request is coming from a logged in User, you can use the "me" object to a this.creator = me._id; -Cancelling an event -------------------- +## Cancelling an event -You can stop any event by calling the cancel(message, [code]) method. +You can stop any event by calling the `cancel(message, [code])` method. //On Delete: if (this.protected) { @@ -200,7 +186,7 @@ You can stop any event by calling the cancel(message, [code]) method. "message": "This post is protected and cannot be deleted" } -You can pass an integer to the cancel() method as the second parameter to set the HTTP status code. For example, 401 means "Unauthorized". +You can pass an integer to the `cancel()` method as the second parameter to set the HTTP status code. For example, 401 means "Unauthorized". //On Put if (this.creator !== me._id) { @@ -217,10 +203,9 @@ You can pass an integer to the cancel() method as the second parameter to set th } -Validation ----------- +## Validation -Use the error(name, message) function to add a validation error. +Use the `error(name, message)` function to add a validation error. //On Post if (this.age < 18) { @@ -241,10 +226,9 @@ Use the error(name, message) function to add a validation error. } } -Hiding properties ------------------ +## Hiding properties -If you wish to hide certain properties from a user, use the hide(propertyName) function. +If you wish to hide certain properties from a user, use the `hide(propertyName)` function. //On Get if (this.creator !== me._id) { @@ -252,10 +236,9 @@ If you wish to hide certain properties from a user, use the hide(propertyName) f hide('age'); } -Protecting properties from modification ---------------------------------------- +## Protecting properties from modification -Use the protect(propertyName) function to protect specified properties during a POST or PUT. +Use the `protect(propertyName)` function to protect specified properties during a POST or PUT. //On Put protect('createdDate'); \ No newline at end of file diff --git a/docs/files.html b/docs/files.html new file mode 100644 index 0000000..0cbed05 --- /dev/null +++ b/docs/files.html @@ -0,0 +1,55 @@ + + + + Deployd Documentation + + + + + +
+
+
+ + Deployd + + + +
+
+
+ +

Files Resource

+ +

The Files Resource allows you host static files from your app, such as HTML, browser JavaScript, CSS, images, and videos.

+ +

Accessing files

+ +

Send a GET request with the filename to load the raw file. This is how browsers request pages and files by default.

+ +
GET /files/bg.jpg
+
+ +

Folders

+ +

If you prefer to have separate folders for Javascript, CSS, and images, create multiple Static Resources at the paths you want to store the files.

+ +

You can also give a Static Resource an empty path /. This will assign it to the root of your app.

+ +

Home page

+ +

If a Static Resource receives a request without a filename, it will automatically redirect to "index.html" if available.

+
+ + + \ No newline at end of file diff --git a/docs/files.markdown b/docs/files.markdown new file mode 100644 index 0000000..16a901c --- /dev/null +++ b/docs/files.markdown @@ -0,0 +1,19 @@ +# Files Resource + +The Files Resource allows you host static files from your app, such as HTML, browser JavaScript, CSS, images, and videos. + +## Accessing files + +Send a GET request with the filename to load the raw file. This is how browsers request pages and files by default. + + GET /files/bg.jpg + +## Folders + +If you prefer to have separate folders for Javascript, CSS, and images, create multiple Static Resources at the paths you want to store the files. + +You can also give a Static Resource an empty path `/`. This will assign it to the root of your app. + +## Home page + +If a Static Resource receives a request without a filename, it will automatically redirect to "index.html" if available. \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 09856db..567a743 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,6 +4,7 @@ Deployd Documentation +
@@ -13,15 +14,81 @@ Deployd +
-
/bin/sh: markdown: command not found +
+
+

Deployd

+

A modern web server for front-end developers.

+
+
+ +

Basics

+ +

Deployd is a web server built on resources, in the style of REST. In the dashboard, you can build your app by creating resources and configuring them to work the way the want.

+ +

Routing

+ +

When Deployd receives an HTTP request, it checks the first part of the URL to see which resource should handle the request:

+ +
    +
  • /todos/12345 - handled by the /todos resource
    • +
  • /admin/users/12345 - handled by the /admin resource, if it exists (you cannot create multi-part resource names)
    • +
  • /img/bg.jpg - handled by the /img resource
    • +
  • /index.html - handled by the / resource
    • +
+ +

Reserved resource names

+ +

Certain resource paths are used internally by Deployd. You should not create resources with these names:

+ +
    +
  • /keys
    • +
  • /types
    • +
  • /resources
    • +
  • /sessions
    • +
  • /property-types
    • +
  • /__dashboard
    • +
+ +

REST

+ +

REST is a web service design pattern that conforms closely to HTTP itself. In Deployd, HTTP methods or verbs have meaning:

+ +
    +
  • GET - Load a resource without modifying it (this is a browser's default method)
    • +
  • POST - Create a resource, or send data to a special that doesn't fit within these methods
    • +
  • PUT - Update an existing resource
    • +
  • DELETE - Destroy an existing resource
    • +
+ +

In Deployd, HTTP response codes are also important:

+ +
    +
  • 200 OK - The request succeeded
    • +
  • 204 No Content - The request succeeded, but there is no content to return (for example, after a deletion, or requesting an empty list)
    • +
  • 400 Bad Request - The request did not pass validation. Change the parameters and try again.
    • +
  • 401 Unauthorized - The request's session does not have permission to access that resource.
    • +
  • 404 Not Found - That URL does not reference an existing resource
    • +
  • 500 Internal Server Error - Deployd has failed to process the request due to an unexpected error.
    • +
+ +

Cross-Origin AJAX

+ +

Deployd is configured so that you can easily develop a web app locally on your computer. It will send Access-Control-Allow-Origin HTTP headers if a request is coming from localhost or your filesystem, which will allow modern web browsers to use AJAX normally. It will not send these headers for any other domain.

diff --git a/docs/layout/header.html b/docs/layout/header.html index 78565e5..ae86687 100644 --- a/docs/layout/header.html +++ b/docs/layout/header.html @@ -4,6 +4,7 @@ Deployd Documentation +
@@ -13,10 +14,17 @@ Deployd +
diff --git a/docs/static.html b/docs/static.html deleted file mode 100644 index 09856db..0000000 --- a/docs/static.html +++ /dev/null @@ -1,28 +0,0 @@ - - - - Deployd Documentation - - - - -
-
-
- - Deployd - - -
-
-
- -
/bin/sh: markdown: command not found -
- - - \ No newline at end of file diff --git a/docs/static.markdown b/docs/static.markdown deleted file mode 100644 index 5cd383f..0000000 --- a/docs/static.markdown +++ /dev/null @@ -1,23 +0,0 @@ -Static Resource -=============== - -The Static Resource allows you host static files from your app, such as HTML, browser JavaScript, CSS, images, and videos. - -Accessing files ---------------- - -Send a GET request with the filename to load the raw file. This is how browsers request pages and files by default. - - GET /files/bg.jpg - -Folders -------- - -If you prefer to have seperate folders for Javascript, CSS, and images, create multiple Static Resources at the paths you want to store the files. - -You can also give a Static Resource an empty path ("/"). This will assign it to the root of your app. - -Home page ---------- - -If a Static Resource receives a request without a filename, it will automatically redirect to "index.html" if available. \ No newline at end of file diff --git a/docs/usercollection.html b/docs/usercollection.html index 09856db..e8ccebc 100644 --- a/docs/usercollection.html +++ b/docs/usercollection.html @@ -4,6 +4,7 @@ Deployd Documentation +
@@ -13,15 +14,76 @@ Deployd +
-
/bin/sh: markdown: command not found +

User Collection Resource

+ +

A User Collection resource behaves much like the standard Collection resource, but adds the ability to authenticate with a username and password.

+ +

Special properties

+ +

The User Collection contains two special properties:

+ +
    +
  • email - For security, hidden by default on all users except the current user.
    • +
  • password - Never readable under any circumstances. Can only be set when the user is logged in, when creating a new user, or from the Dashboard.
    • +
+ +

Registering a user

+ +

First create a user by POSTing it to the root of the collection. +For this example our collection will be called /users.

+ +
POST /users/login
+Content-Type: application/json
+{
+  "email": "foo@bar.com",
+  "password": "barfoo"
+}
+
+ +

Authenticating a user

+ +

To login a user, send a POST request to /<collection name>/login:

+ +
POST /users/login
+Content-Type: application/json
+{
+  "email": "foo@bar.com",
+  "password": "barfoo"
+}
+
+ +

The server will respond with the user, without the password.

+ +
200 OK
+{
+  "_id": "4f71fc7c2ba744786f000001",
+  "email": "foo@bar.com"
+}
+
+ +

Logging out

+ +

To logout a user send a DELETE request to /<collection name>/logout:

+ +
204 No Content
+
+ +

The currently logged in user is available when GETing /users/me.

diff --git a/docs/usercollection.markdown b/docs/usercollection.markdown index 75827a2..69fbf41 100644 --- a/docs/usercollection.markdown +++ b/docs/usercollection.markdown @@ -1,18 +1,15 @@ -User Collection Resource -======================== +# User Collection Resource A User Collection resource behaves much like the standard Collection resource, but adds the ability to authenticate with a username and password. -Special properties ------------------- +## Special properties The User Collection contains two special properties: * **email** - For security, hidden by default on all users except the current user. * **password** - Never readable under any circumstances. Can only be set when the user is logged in, when creating a new user, or from the Dashboard. -Authenticating a user ---------------------- +## Registering a user First create a user by POSTing it to the root of the collection. For this example our collection will be called `/users`. @@ -24,6 +21,8 @@ For this example our collection will be called `/users`. "password": "barfoo" } +## Authenticating a user + To login a user, send a POST request to `//login`: POST /users/login @@ -41,6 +40,8 @@ The server will respond with the user, without the password. "email": "foo@bar.com" } +## Logging out + To logout a user send a DELETE request to `//logout`: 204 No Content From 22d69acc273876b8e642b3f971a4ee6e7c94c9c3 Mon Sep 17 00:00:00 2001 From: Ritchie Date: Tue, 3 Apr 2012 11:48:16 -0700 Subject: [PATCH 2/2] fixed doc link --- docs/collection.html | 2 +- docs/files.html | 2 +- docs/index.html | 2 +- docs/layout/header.html | 2 +- docs/usercollection.html | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/collection.html b/docs/collection.html index 9f47a35..2673322 100644 --- a/docs/collection.html +++ b/docs/collection.html @@ -16,7 +16,7 @@