# Interacting with external resources

Digital Writer includes a resource proxy which enables plugins to make HTTP requests to external resources, even when the Writer is hosted in an IP-locked environment.

In order to reach an external source the plugin should use the built in `Router`-instance which is exposed on the `writer.router`-property. This `router`-property contains functions for the normal HTTP methods, `get()` `post()`, `del()`, and `put()`.

* `api.router.post(string path, object parameters)`
* `api.router.put(string path, object parameters)`
* `api.router.get(string path, object parameters)`
* `api.router.del(string path, object parameters)`

## `path` and `parameters` specification

* `path` is a string which should point to an internal Writer API resource. For the purposes

  of interacting with external sources, `path` should be `'/api/resourceproxy'`
* `parameters` is an object which is converted to a querystring and is appended to the `path` parameter.
  * Use the `url`-property to define which external resource to fetch
  * The `headers`, and `body`-properties are forwarded to the external resource
  * Add a `x-append-authorization`-property to `headers`-property to forward any Authorization

    information to the external resource

## Simple GET of external resource

```javascript
import {api} from 'writer'

api.router.get('/api/resourceproxy', { url: 'https://my-external-url.com' })
    .then(response => api.router.checkForOKStatus(response))
    .then(response => api.router.toJson(response))
    .then(json => {
        // Handle json data
    })
```

## Simple POST to external resource

```javascript
import {api} from 'writer'

api.router.post('/api/resourceproxy', {
    url: 'https://my-external-url.com',
    body: JSON.stringify({
        property: 'value'
    }),
})
    .then(response => api.router.checkForOKStatus(response))
    .then(response => api.router.toJson(response))
    .then(json => {
        // Handle json data
    })
```

## Simple request of external resource with added header

```javascript
import {api} from 'writer'

api.router.get('/api/resourceproxy', { 
    url: 'https://my-external-url.com',
    headers: {
        'x-my-header': 'my-header-value'
    }
})
    .then(response => api.router.checkForOKStatus(response))
    .then(response => api.router.toJson(response))
    .then(json => {
        // Handle json data
    })
```

## POST with Authorization header using `resourceproxy`

```javascript
import {api} from 'writer'

api.router.post('/api/resourceproxy', {
    url: 'https://my-protected-external-url.com',
    body: JSON.stringify({
        property: 'value'
    }),
    headers: {
        'x-append-authorization': 'Basic YWxhZGRpbjpvcGVuc2VzYW1l'
    }
})
    .then(response => api.router.checkForOKStatus(response))
    .then(response => api.router.toJson(response))
    .then(json => {
        // Handle json data
    })
```

## GET with Authorization header using `resourceproxy`

```javascript
import {api} from 'writer'

api.router.get('/api/resourceproxy', {
    url: 'https://my-protected-external-url.com',
    headers: {
        'x-append-authorization': 'Basic YWxhZGRpbjpvcGVuc2VzYW1l'
    }
})
    .then(response => api.router.checkForOKStatus(response))
    .then(response => api.router.toJson(response))
    .then(json => {
        // Handle json data
    })
```