Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Hello Service (parameter parsing)

Build Status Carbon Version

This example is a more elaborate version of our original hello-world example that illustrates the use of parameter and response definitions.

The code defining the service is located in lib/HelloService.js and uses a simple Endpoint object to implement an HTTP GET at the path /hello.

Recall that our original, bare-bones hello-world service looked like this:

__(function() {
  module.exports = o({
    _type: carbon.carbond.Service,
    port: 8888,
    endpoints : {
      hello: o({
        _type: carbon.carbond.Endpoint,
        get: function(req, res) {
          return { msg: "Hello world!" }
        }
      })
    }
  })
})

This example illustrates formally defining the parameters taken and responses returned by our hello endpoint.

__(function() {
  module.exports = o({
    _type: carbon.carbond.Service,
    port: 8888,
    endpoints : {
      hello: o({
        _type: carbon.carbond.Endpoint,

        get: {
          parameters: {
            who: {
              location: 'query', // one of 'path', 'query', 'header', or 'body'
              required: false,
              default: 'world',
              schema: { type: 'string' } // drives parsing and validation (which can also help prevent injection attacks)
            }
          },
          responses: [
            {
              statusCode: 200,
              description: "Success",
              schema: {
                type: 'object',
                properties: {
                  msg: { type: 'string' }
                },
                required: [ 'msg' ],
                additionalProperties: false
              }
            }
          ],
          
          service: function(req, res) {
            return { msg: `Hello ${req.parameters.who}!` }
          }
        }
      })
    }
  })
})

Installing the service

We encourage you to clone the git repository so you can play around with the code.

$ git clone -b carbon-0.7 git@github.com:carbon-io-examples/example__hello-world-service-parameter-parsing.git
$ cd example__hello-world-service-parameter-parsing
$ npm install

Running the service

To run the service:

$ node lib/HelloService

For cmdline help:

$ node lib/HelloService -h

Accessing the service

To access the /hello endpoint:

$ curl localhost:8888/hello
{ msg: "Hello world!" }

$ curl localhost:8888/hello?who=Addison
{ msg: "Hello Addison!" }

Running the unit tests

This example comes with a simple unit test written in Carbon.io's test framework called TestTube. It is located in the test directory.

$ node test/HelloServiceTest

or

$ npm test

Generating API documentation (aglio flavor)

To generate documentation using aglio, install it as a devDependency:

$ npm install -D --no-optional aglio

Using --no-optional speeds up aglio's install time significantly. Then generate the docs using this command:

$ node lib/HelloService gen-static-docs --flavor aglio --out docs/index.html

About

A more elaborate hello world service

Resources

License

Releases

No releases published

Packages

No packages published