www.aleph1.co.uk Git - yaffs-website/blob - vendor/jcalderonzumba/gastonjs/docs/api/index.md

   1 GastonJS HTTP API
   2 ==================
   3 Lets start by saying that the API is **not REST**, is a simple HTTP interface where you can send POST requests with the command you want the browser to execute and the parameters to execute such commands.
   4
   5 This statement can change in the future but that will require all clients to upgrade to the REST implementation.
   6
   7 ##Start the Browser and the API
   8 ```bash
   9 phantomjs --ssl-protocol=any --ignore-ssl-errors=true vendor/jcalderonzumba/gastonjs/src/Client/main.js 8510 1024 768 false 2>&1 >> /tmp/gastonjs.log &
  10 ```
  11 This will start a phantomjs process and the API listening on the 8510 port, the 1024x768 parameters are the width and
  12 height you want the browser to use. The "false" argument is about [JavaScript errors](commands/javascript/set_js_errors.md),
  13 if omitted it'll be "true" by default. You can start the API on the port you want, 8510 is just an example.
  14
  15 ##API endpoint
  16 Your client can start making HTTP POST requests to `http://localhost:8510/v1/api`
  17
  18 ##API command request
  19 Every POST request to the API needs a command name and the arguments that the commands needs to run.
  20
  21 This command is a JSON body that has the following schema:
  22 ```json
  23 {
  24   "name": "COMMAND_NAME",
  25   "args" : [
  26     "COMMAND_ARG_1",
  27     "COMMAND_ARG_2",
  28     ...
  29   ]
  30 }
  31 ```
  32
  33 ##API response
  34 * Successful command execution has an **HTTP 200 status code** and a body:
  35 ```json
  36 {
  37   "response":{
  38     OBJECT_DEPENDS_ON_THE_COMMAND
  39     }
  40 }
  41 ```
  42 * Error while executing command has an **HTTP 500 status code** and a body:
  43 ```json
  44 {
  45   "error": {
  46       "name": "GastonJSExceptionClass",
  47       "args": "ExceptionClassArguments"
  48     }
  49 }
  50 ```
  51
  52 ##API request example
  53 The following example will teach you how to visit a page and save the rendered page:
  54
  55 1. Visit the page:
  56 ```bash
  57 curl -X POST -H "Content-Type: application/json" -d '{"name":"visit","args":["https://www.google.es"]}' 'http://127.0.0.1:8510/v1/api'
  58 ```
  59
  60 2. Save the rendered page to a PNG file:
  61 ```bash
  62 curl -X POST -H "Content-Type: application/json" -d '{"name":"render","args":["/tmp/google.png", true]}' 'http://127.0.0.1:8510/v1/api'
  63 ```
  64
  65 ##Full API command documentation
  66 * [API commands list](command-list.md)