A Hello World Example for JSON

If you change the example slightly, then a JSON object will be delivered.

  1. arangosh> db._routing.save({ 
  2. ........>  url: "/hello/json", 
  3. ........>  content: { 
  4. ........>  contentType: "application/json", 
  5. ........>    body: '{"hello" : "world"}'
  6. ........>  }
  7. ........> });
  8. arangosh> require("internal").reloadRouting()

Show execution results

  1. { 
  2.   "_id" : "_routing/68279", 
  3.   "_key" : "68279", 
  4.   "_rev" : "_ZP4PGjW---" 
  5. }

Hide execution results

Again check with your browser or cURL http://localhost:8529/hello/json

Depending on your browser and installed add-ons you will either see the JSONobject or a download dialog. If your browser wants to open an externalapplication to display the JSON object, you can change the contentType to“text/plain” for the example. This makes it easier to check the example usinga browser. Or use curl to access the server.

  1.  

Show execution results

  1. shell> curl --header 'accept: application/json' --dump - http://localhost:8529/hello/json
  2.  
  3. HTTP/1.1 OK
  4. content-type: application/json; charset=utf-8
  5. x-content-type-options: nosniff
  6.  
  7. { 
  8.   "hello" : "world" 
  9. }

Hide execution results

  1.  

Show execution results

  1.  

Hide execution results

Delivering Content

There are a lot of different ways on how to deliver content. We have alreadyseen the simplest one, where static content is delivered. The fun, however,starts when delivering dynamic content.

Static Content

You can specify a body and a content-type.

  1. arangosh> db._routing.save({
  2. ........>  url: "/hello/contentType",
  3. ........>  content: {
  4. ........>    contentType: "text/html",
  5. ........>    body: "<html><body>Hello World</body></html>"
  6. ........>  }
  7. ........> });
  8. arangosh> require("internal").reloadRouting()

Show execution results

  1. { 
  2.   "_id" : "_routing/68289", 
  3.   "_key" : "68289", 
  4.   "_rev" : "_ZP4PGlW---" 
  5. }

Hide execution results

  1.  

Show execution results

  1. shell> curl --header 'accept: application/json' --dump - http://localhost:8529/hello/contentType
  2.  
  3. HTTP/1.1 OK
  4. content-type: text/html
  5. x-content-type-options: nosniff
  6.  
  7. "Hello World"

Hide execution results

  1.  

Show execution results

  1.  

Hide execution results

If the content type is text/plain then you can use the short-cut

  1. { 
  2.   content: "Hello World" 
  3. }

A Simple Action

The simplest dynamic action is:

  1. { 
  2.   action: { 
  3.     do: "@arangodb/actions/echoRequest" 
  4.   } 
  5. }

It is not advisable to store functions directly in the routing table. It isbetter to call functions defined in modules. In the above example the functioncan be accessed from JavaScript as:

  1. require("@arangodb/actions").echoRequest

The function echoRequest is pre-defined. It takes the request objects andechos it in the response.

The signature of such a function must be

  1. function (req, res, options, next)

Examples

  1. arangosh> db._routing.save({ 
  2. ........>    url: "/hello/echo",
  3. ........>    action: { 
  4. ........>    do: "@arangodb/actions/echoRequest" 
  5. ........>  } 
  6. ........> });

Show execution results

  1. { 
  2.   "_id" : "_routing/68299", 
  3.   "_key" : "68299", 
  4.   "_rev" : "_ZP4PGn6---" 
  5. }

Hide execution results

Reload the routing and check http:// 127.0.0.1:8529/hello/echo

You should see something like

  1. arangosh> arango.GET_RAW("/hello/echo", { "accept" : "application/json" })

Show execution results

  1. { 
  2.   "code" : 200, 
  3.   "error" : false, 
  4.   "body" : "{\"request\":{\"authorized\":true,\"user\":\"root\",\"database\":\"_system\",\"url\":\"/hello/echo\",\"protocol\":\"http\",\"server\":{\"address\":\"127.0.0.1\",\"port\":37891},\"client\":{\"address\":\"127.0.0.1\",\"port\":44042,\"id\":\"156817587559043\"},\"internals\":{},\"headers\":{\"host\":\"127....", 
  5.   "headers" : { 
  6.     "connection" : "Keep-Alive", 
  7.     "content-length" : "467", 
  8.     "content-type" : "application/json; charset=utf-8", 
  9.     "http/1.1" : "OK", 
  10.     "server" : "ArangoDB", 
  11.     "x-content-type-options" : "nosniff" 
  12.   } 
  13. }

Hide execution results

  1.  

Show execution results

  1.  

Hide execution results

The request might contain path, prefix, suffix, and urlParameters_attributes. _path is the complete path as supplied by the user and alwaysavailable. If a prefix was matched, then this prefix is stored in the attributeprefix and the remaining URL parts are stored as an array in suffix. If oneor more parameters were matched, then the parameter values are stored inurlParameters.

For example, if the url description is

  1. { 
  2.   url: { 
  3.     match: "/hello/:name/:action" 
  4.   } 
  5. }

and you request the path /hello/emil/jump, then the request objectwill contain the following attribute

  1. urlParameters: { 
  2.   name: "emil", 
  3.   action: "jump" 
  4. }

Action Controller

As an alternative to the simple action, you can use controllers. A controller isa module, defines the function get, put, post, delete, head,patch. If a request of the corresponding type is matched, the function will becalled.

Examples

  1. arangosh> db._routing.save({ 
  2. ........>  url: "/hello/echo",
  3. ........>  action: { 
  4. ........>    controller: "@arangodb/actions/echoController" 
  5. ........>  } 
  6. ........> });

Show execution results

  1. { 
  2.   "_id" : "_routing/68309", 
  3.   "_key" : "68309", 
  4.   "_rev" : "_ZP4PGp6---" 
  5. }

Hide execution results

Reload the routing and check http:// 127.0.0.1:8529/hello/echo:

  1. arangosh> arango.GET_RAW("/hello/echo", { "accept" : "application/json" })

Show execution results

  1. { 
  2.   "code" : 200, 
  3.   "error" : false, 
  4.   "body" : "{\"request\":{\"authorized\":true,\"user\":\"root\",\"database\":\"_system\",\"url\":\"/hello/echo\",\"protocol\":\"http\",\"server\":{\"address\":\"127.0.0.1\",\"port\":37891},\"client\":{\"address\":\"127.0.0.1\",\"port\":44042,\"id\":\"156817587559043\"},\"internals\":{},\"headers\":{\"host\":\"127....", 
  5.   "headers" : { 
  6.     "connection" : "Keep-Alive", 
  7.     "content-length" : "467", 
  8.     "content-type" : "application/json; charset=utf-8", 
  9.     "http/1.1" : "OK", 
  10.     "server" : "ArangoDB", 
  11.     "x-content-type-options" : "nosniff" 
  12.   } 
  13. }

Hide execution results

  1.  

Show execution results

  1.  

Hide execution results

Prefix Action Controller

The controller is selected when the definition is read. There is a moreflexible, but slower and maybe insecure variant, the prefix controller.

Assume that the url is a prefix match

  1. { 
  2.   url: { 
  3.     match: /hello/*" 
  4.   } 
  5. }

You can use

  1. { 
  2.   action: { 
  3.     prefixController: "@arangodb/actions" 
  4.   } 
  5. }

to define a prefix controller. If the URL /hello/echoController is given, thenthe module @arangodb/actions/echoController is used.

If you use a prefix controller, you should make certain that no unwanted actionsare available under the prefix.

The definition

  1. { 
  2.   action: "@arangodb/actions" 
  3. }

is a short-cut for a prefix controller definition.

Function Action

You can also store a function directly in the routing table.

Examples

  1. arangosh> db._routing.save({ 
  2. ........>  url: "/hello/echo",
  3. ........>  action: { 
  4. ........>    callback: "function(req,res) {res.statusCode=200; res.body='Hello'}" 
  5. ........>  } 
  6. ........> });

Show execution results

  1. { 
  2.   "_id" : "_routing/68319", 
  3.   "_key" : "68319", 
  4.   "_rev" : "_ZP4PGr6---" 
  5. }

Hide execution results

  1. arangosh> arango.GET_RAW("hello/echo", { "accept" : "application/json" })
  2. arangosh> db._query("FOR route IN _routing FILTER route.url == '/hello/echo' REMOVE route in _routing")
  3. arangosh> require("internal").reloadRouting()

Show execution results

  1. { 
  2.   "code" : 200, 
  3.   "error" : false, 
  4.   "body" : "Hello", 
  5.   "headers" : { 
  6.     "connection" : "Keep-Alive", 
  7.     "content-length" : "5", 
  8.     "content-type" : "application/json; charset=utf-8", 
  9.     "http/1.1" : "OK", 
  10.     "server" : "ArangoDB", 
  11.     "x-content-type-options" : "nosniff" 
  12.   } 
  13. }
  14. [object ArangoQueryCursor, count: 0, cached: false, hasMore: false]

Hide execution results

Requests and Responses

The controller must define handler functions which take a request object andfill the response object.

A very simple example is the function echoRequest defined in the module@arangodb/actions.

  1. function (req, res, options, next) {
  2.   var result;
  4.   result = { request: req, options: options };
  6.   res.responseCode = exports.HTTP_OK;
  7.   res.contentType = "application/json";
  8.   res.body = JSON.stringify(result);
  9. }

Install it via:

  1. arangosh> db._routing.save({ 
  2. ........>  url: "/echo",
  3. ........>  action: { 
  4. ........>    do: "@arangodb/actions/echoRequest" 
  5. ........>  }
  6. ........> })

Show execution results

  1. { 
  2.   "_id" : "_routing/68328", 
  3.   "_key" : "68328", 
  4.   "_rev" : "_ZP4PGt6---" 
  5. }

Hide execution results

Reload the routing and check http:// 127.0.0.1:8529/hello/echo

You should see something like

  1. arangosh> arango.GET_RAW("/hello/echo", { "accept" : "application/json" })
  2. arangosh> db._query("FOR route IN _routing FILTER route.url == '/hello/echo' REMOVE route in _routing")
  3. arangosh> require("internal").reloadRouting()

Show execution results

  1. { 
  2.   "code" : 404, 
  3.   "error" : true, 
  4.   "errorNum" : 404, 
  5.   "errorMessage" : "404 Not Found", 
  6.   "body" : "{\"error\":true,\"code\":404,\"errorNum\":404,\"errorMessage\":\"unknown path '/hello/echo'\"}", 
  7.   "headers" : { 
  8.     "connection" : "Keep-Alive", 
  9.     "content-length" : "84", 
  10.     "content-type" : "application/json; charset=utf-8", 
  11.     "http/1.1" : "Not Found", 
  12.     "server" : "ArangoDB", 
  13.     "x-content-type-options" : "nosniff" 
  14.   } 
  15. }
  16. [object ArangoQueryCursor, count: 0, cached: false, hasMore: false]

Hide execution results

You may also pass options to the called function:

  1. arangosh> db._routing.save({ 
  2. ........>  url: "/echo",
  3. ........>  action: {
  4. ........>    do: "@arangodb/actions/echoRequest",
  5. ........>    options: { 
  6. ........>      "Hello": "World" 
  7. ........>    }
  8. ........>  } 
  9. ........> });

Show execution results

  1. { 
  2.   "_id" : "_routing/68337", 
  3.   "_key" : "68337", 
  4.   "_rev" : "_ZP4PGvm---" 
  5. }

Hide execution results

You now see the options in the result:

  1. arangosh> arango.GET_RAW("/echo", { accept: "application/json" })
  2. arangosh> db._query("FOR route IN _routing FILTER route.url == '/echo' REMOVE route in _routing")
  3. arangosh> require("internal").reloadRouting()

Show execution results

  1. { 
  2.   "code" : 200, 
  3.   "error" : false, 
  4.   "body" : "{\"request\":{\"authorized\":true,\"user\":\"root\",\"database\":\"_system\",\"url\":\"/echo\",\"protocol\":\"http\",\"server\":{\"address\":\"127.0.0.1\",\"port\":37891},\"client\":{\"address\":\"127.0.0.1\",\"port\":44042,\"id\":\"156817587559043\"},\"internals\":{},\"headers\":{\"host\":\"127.0.0.1\"...", 
  5.   "headers" : { 
  6.     "connection" : "Keep-Alive", 
  7.     "content-length" : "461", 
  8.     "content-type" : "application/json; charset=utf-8", 
  9.     "http/1.1" : "OK", 
  10.     "server" : "ArangoDB", 
  11.     "x-content-type-options" : "nosniff" 
  12.   } 
  13. }
  14. [object ArangoQueryCursor, count: 0, cached: false, hasMore: false]

Hide execution results