<commit_before>class Endpoint
----------

An ```Endpoint``` is a representation of a RESTFul resource. Each endpoint can implement one or more operations representing each of the HTTP methods: ```GET```, ```PUT```, ```POST```, ```CREATE```, ```DELETE```, ```HEAD```, ```OPTIONS```. 

Endpoints can also define child endpoints whose paths will be interpreted relative to the ```path``` of this ```Endpoint``` object.

Configuration
----------

```
{
  _type: carbon.carbond.Endpoint,
  
  [get: <function> | <Operation>],
  [put: <function> | <Operation>],
  [post: <function> | <Operation>],
  [create: <function> | <Operation>],
  [delete: <function> | <Operation>],
  [head: <function> | <Operation>],
  [options: <function> | <Operation>],

  [endpoints: { 
    <path>: <Endpoint>
    ...
  }]
}
```

Properties
----------

* ```path``` (read-only) - the path to which this endpoint is bound. The path can contain variable patterns (e.g. ```'orders/:id'```). The ```path``` property is not configured directly on ```Endpoint``` objects but are specified as lvals in enclosing defininitions of endpoints such as in an ```ObjectServer``` or a parent ```Endpoint``` object. When retrieved the value of this property will be the absolute path of the endpoint from ```/```. 

* ```objectserver``` (read-only) - the ```ObjectServer``` to which this endpoint belongs

* ```endpoints``` - a set of child ```Endpoint``` definitions. This is an object whose keys are path strings and values are instances of ```Endpoint```. Each path key will be interpreted as relative to this ```Endpoint```s ```path``` property. 

Operations
----------

Each endpoint can implement one or more operations representing each of the HTTP methods: ```GET```, ```PUT```, ```POST```, ```CREATE```, ```DELETE```, ```HEAD```, ```OPTIONS```. There is no requirement an endpoint implement all HTTP methods. It only needs to implement those it wishes to support.

Each operation is represented as either:
* A function of the form ```function(req, res)```
* An ```Operation``` object. This is more elaborate definition which allows for a description, parameter definitions, and other useful meta-data as well as a ```service``` method of the form ```function(req, res)```

When responding to HTTP requests, two styles are supported:
* An asynchronous style where operations write directly to the ```HttpResponse``` object passed to the operation. This style is useful when the operation needs to manipulate the ```HttpResponse``` object to do more than simply return JSON (e.g. set HTTP headers), or wished to pass the response to other functions.
* A synchronous style where the operation simply returns a JSON object from the operation, or throws an exception to signal an error condition. When using this style the ```HttpResponse``` parameter can be omitted from the function signature of the operation. This style is useful when programming in a more synchronous style and / or coordinating with exceptions thrown deeper in the call stack.

**Examples (asynchronous)**
```node
get: function(req, res) {
  res.send({ msg: "hello world!" })  
}
```

```node
get: {
  description: "My hello world operation",
  params: {}
  service: function(req, res) {
    res.send({ msg: "hello world!" })  
  }
}
```

**Examples (synchronous)**
```node
get: function(req) {
  return { msg: "hello world!" }
}
```

```node
get: {
  description: "My hello world operation",
  params: {}
  service: function(req) {
    return { msg: "hello world!" }
  }
}
```

*XXX come back to talk about error handling*

### Operation details

#### get
Implementation of HTTP ```GET```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### put
Implementation of HTTP ```PUT```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### post
Implementation of HTTP ```POST```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### create
Implementation of HTTP ```CREATE```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### delete
Implementation of HTTP ```DELETE```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### head
Implementation of HTTP ```HEAD```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)
  
If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### options
Implementation of HTTP ```OPTIONS```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

Examples
----------

```node
var o = require('maker').o(module, true)

module.exports = o({
  _type: 'datanode/ObjectServer',
  port: 8888,
  endpoints: {
    hello: o({
      _type: 'datanode/Endpoint',
      get: function(req) {
        return { msg: "Hello World!" }
      }
    })
  }
})
```

<commit_msg>Update Endpoint.md<commit_after>class Endpoint
----------

An ```Endpoint``` is a representation of a RESTFul resource. Each endpoint can implement one or more operations representing each of the HTTP methods: ```GET```, ```PUT```, ```POST```, ```CREATE```, ```DELETE```, ```HEAD```, ```OPTIONS```. 

Endpoints can also define child endpoints whose paths will be interpreted relative to the ```path``` of this ```Endpoint``` object.

Configuration
----------

```
{
  _type: carbon.carbond.Endpoint,
  
  [get: <function> | <Operation>],
  [put: <function> | <Operation>],
  [post: <function> | <Operation>],
  [create: <function> | <Operation>],
  [delete: <function> | <Operation>],
  [head: <function> | <Operation>],
  [options: <function> | <Operation>],

  [endpoints: { 
    <path>: <Endpoint>
    ...
  }]
}
```

Properties
----------

* ```path``` (read-only) - the path to which this endpoint is bound. The path can contain variable patterns (e.g. ```'orders/:id'```). The ```path``` property is not configured directly on ```Endpoint``` objects but are specified as lvals in enclosing defininitions of endpoints such as in an ```ObjectServer``` or a parent ```Endpoint``` object. When retrieved the value of this property will be the absolute path of the endpoint from ```/```. 

* ```objectserver``` (read-only) - the ```ObjectServer``` to which this endpoint belongs

* ```endpoints``` - a set of child ```Endpoint``` definitions. This is an object whose keys are path strings and values are instances of ```Endpoint```. Each path key will be interpreted as relative to this ```Endpoint```s ```path``` property. 

Operations
----------

Each endpoint can implement one or more operations representing each of the HTTP methods: ```GET```, ```PUT```, ```POST```, ```CREATE```, ```DELETE```, ```HEAD```, ```OPTIONS```. There is no requirement an endpoint implement all HTTP methods. It only needs to implement those it wishes to support.

Each operation is represented as either:
* A function of the form ```function(req, res)```
* An ```Operation``` object. This is more elaborate definition which allows for a description, parameter definitions, and other useful meta-data as well as a ```service``` method of the form ```function(req, res)```

When responding to HTTP requests, two styles are supported:
* An asynchronous style where operations write directly to the ```HttpResponse``` object passed to the operation. This style is useful when the operation needs to manipulate the ```HttpResponse``` object to do more than simply return JSON (e.g. set HTTP headers), or wished to pass the response to other functions.
* A synchronous style where the operation simply returns a JSON object from the operation, or throws an exception to signal an error condition. When using this style the ```HttpResponse``` parameter can be omitted from the function signature of the operation. This style is useful when programming in a more synchronous style and / or coordinating with exceptions thrown deeper in the call stack.

**Examples (asynchronous)**
```node
get: function(req, res) {
  res.send({ msg: "hello world!" })  
}
```

```node
get: {
  description: "My hello world operation",
  params: {}
  service: function(req, res) {
    res.send({ msg: "hello world!" })  
  }
}
```

**Examples (synchronous)**
```node
get: function(req) {
  return { msg: "hello world!" }
}
```

```node
get: {
  description: "My hello world operation",
  params: {}
  service: function(req) {
    return { msg: "hello world!" }
  }
}
```

*XXX come back to talk about error handling*

### Operation details

#### get
Implementation of HTTP ```GET```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### put
Implementation of HTTP ```PUT```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### post
Implementation of HTTP ```POST```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### create
Implementation of HTTP ```CREATE```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### delete
Implementation of HTTP ```DELETE```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### head
Implementation of HTTP ```HEAD```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)
  
If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

#### options
Implementation of HTTP ```OPTIONS```. Either a ```function``` or an ```Operation``` object. 

If the operation is defined by a function it will have these parameters:
  * ```req```: the ```HttpRequest``` object
  * ```res```: the ```HttpResponse``` object (can be omitted if using a synchronous style)

If the operation is defined by an ```Operation``` object the definition will have a ```service``` method of the same signature.

Examples
----------

```node
var carbon = require('carbon.io')
var o = carbon.atom.o(module)

module.exports = o({
  _type: carbon.carbond.ObjectServer,
  port: 8888,
  endpoints: {
    hello: o({
      _type: carbon.carbond.Endpoint,
      get: function(req) {
        return { msg: "Hello World!" }
      }
    })
  }
})
```


{'fraction_non_alphanumeric': 0.15546819156540387, 'fraction_numerical': 0.0005718370264474624, 'mean_word_length': 4.397762345679013, 'pattern_counts': {'":': 0, '<': 35, '<?xml version=': 0, '>': 35, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1322807', 'n_tokens_mistral': 3804, 'n_tokens_neox': 3725, 'n_words': 1801}