Open api/0.12 spec

[alecritson]

This PR has various updates to the spec to get ready for 0.12

Notably I've added some initial include descriptions for resources, update some examples and update query params for some important routes.

[glennjacobs]

• Need to ensure all examples are real-world (no "string" entries for example) and helpful.
• When includes are available, we need to list what can be requested, e.g. product, category or whatever and include plenty of examples too. Eg. products with their variants.
• Same for any other fields, we need to suggest what they're expecting - remove the guesswork.

Real example requests and responses will help loads in understanding the API.

[glennjacobs]

Also worth noting we do not have any spec for the recycle bin restore function.

[glennjacobs]

Channels

GET /channels

{
  "data": [
    {
      "id": "y3g6v91o",
      "name": "Webstore",
      "handle": "webstore",
      "url": "localhost:8080",
      "default": true
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 24,
    "last_page": 15,
    "path": "string",
    "per_page": 1,
    "to": 0,
    "total": 0,
    "links": [
      {
        "url": "string",
        "label": "string",
        "active": true
      }
    ]
  }
}

Need to replace the "string" entries with something meaningful.

POST + PUT /channels

Missing example request.

GET /channels/{channelId}

Example request in PHP not JSON.

[glennjacobs]

{
  "data": [
    {
      "id": "y3g6v91o",
      "name": "Webstore",
      "handle": "webstore",
      "url": "localhost:8080",
      "default": true
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 24,
    "last_page": 15,
    "path": "http:\\/\\/api.test\\/api\\/v1\\/channels",
    "per_page": 1,
    "to": 0,
    "total": 0,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "http://api.test/api/v1/channels?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next »",
        "active": false
      }
    ]
  }
}

URLs are showing in two different formats?