bw-cli/docs/RESTfulData.md

The Brightwork (bw) command line deployment tool. Build & deploy serverless RESTful APIs in minutes.

## <span id="restful-data">RESTful Data</a>
Out of the box brightwork offers the ability to define models with relationships and automatically generate restful endpoints.

### <span id="defining-models">Defining models</a>
- Edit manifest.yml

Now you can add your models using your favorite editor.  Below we outline some conventions for defining models.

#### Model attributes

You can define model attributes using shorthand `field: type` when your field has no options.

##### Allowed types
- string
- text
- integer
- float
- date
- datetime
- boolean
- binary
- array
- json
- mediumtext
- longtext
- objectid

##### Options
- required (true | false)
- default (value)
- unique (true | false)
- enum ([] of values)
- autoIncrement (true | false, integer only)

##### Associations

**One Way**

To create a one way associate simple add a model property to the field with the name of the model to associate.

*For Example, photo has an album linked via photo.album*

```yaml
models:
  album:
    attributes:
      name: string
  photo:
    attributes:
      caption: string
      url: string
      album:
        model: &#39;album&#39;
```
**One to Many**

To create a one to many association we will expand on a one way associate by adding a collection to the parent.

*For Example, photo has an album linked via photos.album -> album has many photos linked via album.photos -> photo*

```yaml
models:
  album:
    attributes:
      name: string
      photos:
        collection: 'photo'
        via: 'album'
  photo:
    attributes:
      caption: string
      url: string
      album:
        model: 'album'
```

### <span id="deploy-your-api">Deploy your API</a>
```bash
bw push
```

### <span id="get-your-api-key">Get your API key</a>

```bash
bw list
```

### <span id="try-your-api">Try your API</a>
Once you have deployed BrightWork will host your API at: `http://appname.bwapps.io/`

Given the album example above the following endpoints are available:

| Endpoint                                         | Method|  Description                    |
| ------------------------------------------------ | ----- | ------------------------------- |
| http://appname.bwapps.io/api/album            | GET   | Get all albums                   |
| http://appname.bwapps.io/api/album/:id        | GET   | Get album for specified id       |
| http://appname.bwapps.io/api/album            | POST  | Create new album                 |
| http://appname.bwapps.io/api/album/:id        | PUT   | Update an existing user         |
| http://appname.bwapps.io/api/album/:id        | DELETE | Delete user for specified id    |
| http://appname.bwapps.io/api/album/:id/photos   | GET   | Get photos for the specified album |
| http://appname.bwapps.io/api/photo             | GET   | Get all photos                    |
| http://appname.bwapps.io/api/photo/:id         | GET   | Get photo for specified id        |
| http://appname.bwapps.io/api/photo             | POST  | Create new photo                  |
| http://appname.bwapps.io/api/photo/:id         | PUT   | Update an existing photo          |
| http://appname.bwapps.io/api/photo/:id         | DELETE | Delete photo for specified id     |
| ------------------------------------------------ | ----- | ------------------------------- |
_**you can now use shorter urls, we've removed the need to have appname in the api path**_

_now:_ _`http://appname.bwapps.io/api/model`_

_previously:_ _`http://appname.bwapps.io/api/appname/model`_

**Required Headers**

- apikey: --YOUR KEY--

**Sample Request**
Assumes your following allong with the album analogy above.
```javascript
curl -X POST -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"name": "Abbey Road" }' "http://appname.bwapps.io/api/album/"
```

**Sample Response**
```json
{
  "name": "Abbey Road",
  "createdAt": "2016-05-05T17:51:01.291Z",
  "updatedAt": "2016-05-05T17:51:01.291Z",
  "id": "572b8805db6acd190082ec6b"
}
```

**Sample Query for Albums**
```javascript
curl -X GET -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" \
"http://appname.bwapps.io/api/album/"
```
**Sample Response**
```json
[{
  "name": "Abbey Road",
  "createdAt": "2016-05-05T17:51:01.291Z",
  "updatedAt": "2016-05-05T17:51:01.291Z",
  "id": "572b8805db6acd190082ec6b"
}]
```

## <span id="contact-and-support">Contact & Support</a>
We're always trying to improve our product. Get in touch with us by email: <support@brightwork.io>