# rest-agenda API documentation version 0.1.0

/

### Getting Started

# REST-Scheduler

## Introduction

`rest-scheduler` is middleware that allows the creation and management of special tasks. Think about it as an API to cron w/ persistence and clustering, not all tasks are automations. This is a dumb system.

## Getting started

### Mongo

Currently agenda only supports Mongo 2.6.x - <3.0 A Dockerfile is included in this project for convenience

please note that `NODE_ENV` must be set per environment, example files are included in the repo

    $ cp .env.sample .env

then edit `.env` as required, the default mongo docker container does not require `dbuser` or `dbpassword`

    {
      MONGOSTRING: "mongodb://<dbuser>:<dbpassword>@<domain>:<port>/<database>", // use whatever mongo connect string you need
      "NODE_ENV": "development"                                                  // set whatever environment you want
    }

### Start REST-Scheduler

Now that we have our environment variables taken care of

Run Mongo then start the server

    $ node run docker
    $ node server.js                                        // if you want stdout
    or
    $ pm2 start server.js --name=rest-scheduler --watch     // if you want the awesomeness of pm2

### Start Agendash

to run agendash, in a separate process (open a new terminal window) run:

    $ ./node_modules/.bin/agendash --db=mongodb://<mongouser>:<mongopass>@<mongoserver>:<mongoport>/<mongodb> --port=3001

alternatively `.env` may be used to specify this value

This service only exposes a single endpoint... `/action`

## Sending a request to the scheduler

Each request must be sent via POST and contain a request object. Currently only 3 keys are required

    {
    "when":"in 3 second",                       // a relative amount of time
    "url":"http://localhost:3000/testcburl",    // a callback url (all callback urls will be requested via POST)
    "name":"3 job"                              // a name for the job. unique value is encouraged, but not required
    }

### Using HTTP

    POST /action HTTP/1.1
    Host: localhost:3000
    Content-Type: application/json

    {
    "when":"in 3 second",
    "url":"http://localhost:3000/testcburl",
    "name":"3 job"
    }

### Using cURL

    curl -X POST -H "Content-Type: application/json" -d '{
    "when":"in 3 second",
    "url":"http://localhost:3000/testcburl",
    "name":"3 job"
    }' "http://localhost:3000/action"

## Response objects

As REST-Scheduler is really just designed to fire a dumb request to a callback URI after a set period of time, any request object sent to REST-Scheduler will get sent do the callback URI specified in the original request. This can include any arbitrary JSON the original caller desires.

Below is an example of a current response object

    {
      "meta": {
        "time": "2016-03-18T06:54:25.567Z",
        "request": {
          "name": "1 job",
          "data": {
            "when": "in 1 second",
            "url": "http://localhost:3000/testcburl",
            "name": "1 job"
          },
          "type": "normal",
          "priority": 0,
          "nextRunAt": "2016-03-18T06:54:26.568Z",
          "_id": "56eba62139a48fc980b3495d"
        }
      }
    }

Though the original request object can be found at `meta.request.data` in the near future a payload key may be made available as a top level value.

Users are not be limited to a single payload key, and any key in the original request object named other than `meta`, `when`, `url`, or `name` will be passed forward as top level keys and sent to the callback url

    {
      "meta": {
        "time": "2016-03-18T06:54:25.567Z",
        "request": {
          "name": "1 job",
          "data": {
            "when": "in 1 second",
            "url": "http://localhost:3000/testcburl",
            "name": "1 job",
            "foo": ["bar","baz"]            // this is the arbitrarily named payload to make available to the callback url when the scheduled event gets fired
          },
          "type": "normal",
          "priority": 0,
          "nextRunAt": "2016-03-18T06:54:26.568Z",
          "_id": "56eba62139a48fc980b3495d"
        }
      },
      "foo": ["bar","baz"]                  // this is the payload available as a top level key in the request object that gets sent to the callback url
    }

### Create Job

this is the action that will fire at some time in the future

#### / post

post

Add a new to REST-Scheduler.

#### post /

Add a new to REST-Scheduler.

### Headers

- Content-Type: (string )

  the required content type and encoding

  Example:

      application/json; charset=utf-8

### Body

Type: application/json

Schema:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "/",
      "type": "object",
      "properties": {
        "when": {
          "id": "when",
          "type": "string"
        },
        "url": {
          "id": "url",
          "type": "string"
        },
        "name": {
          "id": "name",
          "type": "string"
        }
      },
      "additionalProperties": true,
      "required": [
        "when",
        "url",
        "name"
      ]
    }

Example:

    {
      "when":"in 3 second",
      "url":"http://localhost:3000/testcburl",
      "name":"3 job"
    }

## HTTP status code 200

### Headers

- Content-Type: (string )

  the required content type and encoding

  Example:

      application/json; charset=utf-8

### Body

Type: application/json

Schema:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "/",
      "type": "object",
      "properties": {
        "meta": {
          "id": "meta",
          "type": "object",
          "properties": {
            "time": {
              "id": "time",
              "type": "string"
            },
            "request": {
              "id": "request",
              "type": "object",
              "properties": {
                "name": "[object Object]",
                "data": {
                  "id": "data",
                  "type": "object",
                  "properties": {
                    "when": {
                      "id": "when",
                      "type": "string"
                    },
                    "url": {
                      "id": "url",
                      "type": "string"
                    },
                    "name": "[object Object]"
                  },
                  "additionalProperties": true
                },
                "type": {
                  "id": "type",
                  "type": "string"
                },
                "priority": {
                  "id": "priority",
                  "type": "integer"
                },
                "nextRunAt": {
                  "id": "nextRunAt",
                  "type": "string"
                },
                "_id": {
                  "id": "_id",
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "required": [
            "time",
            "request"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "meta"
      ]
    }

Example:

    {
      "meta": {
        "time": "2016-03-18T06:54:25.567Z",
        "request": {
          "name": "1 job",
          "data": {
            "when": "in 1 second",
            "url": "http://localhost:3000/testcburl",
            "name": "1 job"
          },
          "type": "normal",
          "priority": 0,
          "nextRunAt": "2016-03-18T06:54:26.568Z",
          "_id": "56eba62139a48fc980b3495d"
        }
      }
    }

## HTTP status code 400

### Headers

- Content-Type: (string )

  the required content type and encoding

  Example:

      application/json; charset=utf-8

### Body

Type: application/json

Example:

    {"message": "We could not process your request " }

## HTTP status code 500

### Headers

- Content-Type: (string )

  the required content type and encoding

  Example:

      application/json; charset=utf-8

### Body

Type: application/json

Example:

    {"message": "Job  could not be created" }

### Job

this is the action that will fire at some time in the future

#### /{jobid} get put delete

get

Get the with Id = {Id}

put

Update the with Id = {Id}.

delete

#### get /{jobid}

Get the with Id = {Id}

### URI Parameters

- jobid: required (string )

### Headers

- Content-Type: (string )

  the required content type and encoding

  Example:

      application/json; charset=utf-8

## HTTP status code 200

### Headers

- Content-Type: (string )

  the required content type and encoding

  Example:

      application/json; charset=utf-8

### Body

Type: application/json

Schema:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "/",
      "type": "object",
      "properties": {
        "meta": {
          "id": "meta",
          "type": "object",
          "properties": {
            "time": {
              "id": "time",
              "type": "string"
            },
            "request": {
              "id": "request",
              "type": "object",
              "properties": {
                "name": "[object Object]",
                "data": {
                  "id": "data",
                  "type": "object",
                  "properties": {
                    "when": {
                      "id": "when",
                      "type": "string"
                    },
                    "url": {
                      "id": "url",
                      "type": "string"
                    },
                    "name": "[object Object]"
                  },
                  "additionalProperties": true
                },
                "type": {
                  "id": "type",
                  "type": "string"
                },
                "priority": {
                  "id": "priority",
                  "type": "integer"
                },
                "nextRunAt": {
                  "id": "nextRunAt",
                  "type": "string"
                },
                "_id": {
                  "id": "_id",
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "required": [
            "time",
            "request"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "meta"
      ]
    }

Example:

    {
      "meta": {
        "time": "2016-03-18T06:54:25.567Z",
        "request": {
          "name": "1 job",
          "data": {
            "when": "in 1 second",
            "url": "http://localhost:3000/testcburl",
            "name": "1 job"
          },
          "type": "normal",
          "priority": 0,
          "nextRunAt": "2016-03-18T06:54:26.568Z",
          "_id": "56eba62139a48fc980b3495d"
        }
      }
    }

## HTTP status code 400

### Headers

- Content-Type: (string )

  the required content type and encoding

  Example:

      application/json; charset=utf-8

### Body

Type: application/json

Example:

    {"message": " not found" }

#### put /{jobid}

Update the with Id = {Id}.

### URI Parameters

- jobid: required (string )

### Headers

- Content-Type: (string )

  the required content type and encoding

  Example:

      application/json; charset=utf-8

### Body

Type: application/json

Schema:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "/",
      "type": "object",
      "properties": {
        "meta": {
          "id": "meta",
          "type": "object",
          "properties": {
            "time": {
              "id": "time",
              "type": "string"
            },
            "request": {
              "id": "request",
              "type": "object",
              "properties": {
                "name": "[object Object]",
                "data": {
                  "id": "data",
                  "type": "object",
                  "properties": {
                    "when": {
                      "id": "when",
                      "type": "string"
                    },
                    "url": {
                      "id": "url",
                      "type": "string"
                    },
                    "name": "[object Object]"
                  },
                  "additionalProperties": true
                },
                "type": {
                  "id": "type",
                  "type": "string"
                },
                "priority": {
                  "id": "priority",
                  "type": "integer"
                },
                "nextRunAt": {
                  "id": "nextRunAt",
                  "type": "string"
                },
                "_id": {
                  "id": "_id",
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "required": [
            "time",
            "request"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "meta"
      ]
    }

Example:

    {
      "meta": {
        "time": "2016-03-18T06:54:25.567Z",
        "request": {
          "name": "1 job",
          "data": {
            "when": "in 1 second",
            "url": "http://localhost:3000/testcburl",
            "name": "1 job"
          },
          "type": "normal",
          "priority": 0,
          "nextRunAt": "2016-03-18T06:54:26.568Z",
          "_id": "56eba62139a48fc980b3495d"
        }
      }
    }

## HTTP status code 200

### Headers

- Content-Type: (string )

  the required content type and encoding

  Example:

      application/json; charset=utf-8

### Body

Type: application/json

Schema:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "/",
      "type": "object",
      "properties": {
        "meta": {
          "id": "meta",
          "type": "object",
          "properties": {
            "time": {
              "id": "time",
              "type": "string"
            },
            "request": {
              "id": "request",
              "type": "object",
              "properties": {
                "name": "[object Object]",
                "data": {
                  "id": "data",
                  "type": "object",
                  "properties": {
                    "when": {
                      "id": "when",
                      "type": "string"
                    },
                    "url": {
                      "id": "url",
                      "type": "string"
                    },
                    "name": "[object Object]"
                  },
                  "additionalProperties": true
                },
                "type": {
                  "id": "type",
                  "type": "string"
                },
                "priority": {
                  "id": "priority",
                  "type": "integer"
                },
                "nextRunAt": {
                  "id": "nextRunAt",
                  "type": "string"
                },
                "_id": {
                  "id": "_id",
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "required": [
            "time",
            "request"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "meta"
      ]
    }

Example:

    {
      "meta": {
        "time": "2016-03-18T06:54:25.567Z",
        "request": {
          "name": "1 job",
          "data": {
            "when": "in 1 second",
            "url": "http://localhost:3000/testcburl",
            "name": "1 job"
          },
          "type": "normal",
          "priority": 0,
          "nextRunAt": "2016-03-18T06:54:26.568Z",
          "_id": "56eba62139a48fc980b3495d"
        }
      }
    }

## HTTP status code 400

### Headers

- Content-Type: (string )

  the required content type and encoding

  Example:

      application/json; charset=utf-8

### Body

Type: application/json

Example:

    {"message": "Job  not found" }

#### delete /{jobid}

### URI Parameters

- jobid: required (string )

## HTTP status code 200

### Body

Type: application/json

Schema:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "/",
      "type": "object",
      "properties": {
        "meta": {
          "id": "meta",
          "type": "object",
          "properties": {
            "time": {
              "id": "time",
              "type": "string"
            },
            "request": {
              "id": "request",
              "type": "object",
              "properties": {
                "name": "[object Object]",
                "data": {
                  "id": "data",
                  "type": "object",
                  "properties": {
                    "when": {
                      "id": "when",
                      "type": "string"
                    },
                    "url": {
                      "id": "url",
                      "type": "string"
                    },
                    "name": "[object Object]"
                  },
                  "additionalProperties": true
                },
                "type": {
                  "id": "type",
                  "type": "string"
                },
                "priority": {
                  "id": "priority",
                  "type": "integer"
                },
                "nextRunAt": {
                  "id": "nextRunAt",
                  "type": "string"
                },
                "_id": {
                  "id": "_id",
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "required": [
            "time",
            "request"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "meta"
      ]
    }

Example:

    {
      "meta": {
        "time": "2016-03-18T06:54:25.567Z",
        "request": {
          "name": "1 job",
          "data": {
            "when": "in 1 second",
            "url": "http://localhost:3000/testcburl",
            "name": "1 job"
          },
          "type": "normal",
          "priority": 0,
          "nextRunAt": "2016-03-18T06:54:26.568Z",
          "_id": "56eba62139a48fc980b3495d"
        }
      }
    }

### Callback URL for testing

Entity representing a read-only testcburl

#### /testcburl post

post

Test the testcburl with testcburlId = {testcburlId} If called anonymously, the testcburl must be public.

#### post /testcburl

Test the testcburl with testcburlId = {testcburlId} If called anonymously, the testcburl must be public.

### Body

Type: application/json

Schema:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "/",
      "type": "object",
      "properties": {
        "meta": {
          "id": "meta",
          "type": "object",
          "properties": {
            "time": {
              "id": "time",
              "type": "string"
            },
            "request": {
              "id": "request",
              "type": "object",
              "properties": {
                "name": "[object Object]",
                "data": {
                  "id": "data",
                  "type": "object",
                  "properties": {
                    "when": {
                      "id": "when",
                      "type": "string"
                    },
                    "url": {
                      "id": "url",
                      "type": "string"
                    },
                    "name": "[object Object]"
                  },
                  "additionalProperties": true
                },
                "type": {
                  "id": "type",
                  "type": "string"
                },
                "priority": {
                  "id": "priority",
                  "type": "integer"
                },
                "nextRunAt": {
                  "id": "nextRunAt",
                  "type": "string"
                },
                "_id": {
                  "id": "_id",
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "required": [
            "time",
            "request"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "meta"
      ]
    }
    #testcburl

Example:

    {
      "meta": {
        "time": "2016-03-18T06:54:25.567Z",
        "request": {
          "name": "1 job",
          "data": {
            "when": "in 1 second",
            "url": "http://localhost:3000/testcburl",
            "name": "1 job"
          },
          "type": "normal",
          "priority": 0,
          "nextRunAt": "2016-03-18T06:54:26.568Z",
          "_id": "56eba62139a48fc980b3495d"
        }
      }
    }

## HTTP status code 200

### Body

Type: application/json

Schema:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "/",
      "type": "object",
      "properties": {
        "meta": {
          "id": "meta",
          "type": "object",
          "properties": {
            "time": {
              "id": "time",
              "type": "string"
            },
            "request": {
              "id": "request",
              "type": "object",
              "properties": {
                "name": "[object Object]",
                "data": {
                  "id": "data",
                  "type": "object",
                  "properties": {
                    "when": {
                      "id": "when",
                      "type": "string"
                    },
                    "url": {
                      "id": "url",
                      "type": "string"
                    },
                    "name": "[object Object]"
                  },
                  "additionalProperties": true
                },
                "type": {
                  "id": "type",
                  "type": "string"
                },
                "priority": {
                  "id": "priority",
                  "type": "integer"
                },
                "nextRunAt": {
                  "id": "nextRunAt",
                  "type": "string"
                },
                "_id": {
                  "id": "_id",
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false,
          "required": [
            "time",
            "request"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "meta"
      ]
    }

Example:

    {}