Skip to main content

Publish API

Promaster-edit can publish data to any server that implements the API specified here. A Promaster API server may be built on any platform using any programming language as long as it can adhere to the specification presented here.

File transfers

The Promaster Publish API is built on the concept of files transfers and file references. The server will transfer files to the server implementing the API by using HTTP multipart/form-data POST requests. This allows several files to be transfered in one request. A file that is posted can contain references to other files. The implementing server will check if any of the referenced files are missing and reply with an array of missing files. If promaster-edit receives an array of missing files, it will make another POST with those files and this process is repeated until zero missing files are returned.

The "save" query string parameter

When replacing a file that is being used as entry point for the clients (for example markers.json) it is important that all the referenced files are present before the file is saved and served to clients. If the file is saved with missing references, then the clients cannot be fully served. For this reason the Publish API specifies a query string parameter save that can have values of ifcomplete, no, yes. If the parameter is missing the default is yes which means that the file should be unconditionally saved. A value of no means the file should never be saved (this can be used to only check for missing references), and a value of ifcomplete means that it should be saved only if no refrenced files are missing. For files that are not entrypoints the parameter will not be set so they will always be saved as the default behaviour is yes.

File format

The files that are posted can either be binary files or JSON files. The file name to be used is indicated by the Content-Disposition field for each file in the request. The type of file is indicated by the Content-Type field for each file in the requst. It will be application/json or application/octet-stream. If the file is JSON then it can have references to other files. The base format for the JSON files is this:

{
  "data": {
    // The data section depends on the type of file and it may contain
    // references to the numbers in the "refs" section.
  },
  "refs": {
    // The refs section contains numeric references to other file names
    "0": "otherfile.json",
    "1": "yetotherfile.json",
    "2": "andyetanotherfile.json"
  }
}

Response format

The response is in JSON format and will indicate any missing files that is referenced by the refs section of a posted JSON file.

{
  "missingFiles": ["otherfile.json", "yetotherfile.json"]
}

Example interaction

POST #1 by promaster-edit

  • POST: http://target-server/publish?save=ifcomplete
  • Content-Type: multipart/form-data; boundary=----WebKitFormBoundarywcYaMcsEONHWWBak
------WebKitFormBoundarywcYaMcsEONHWWBak
Content-Disposition: form-data; name="file"; filename="markers.json"
Content-Type: application/json

{
  "data": {
    "marker1": 0,
    "marker2": 1,
    "marker3": 1,
  },
  "refs": {
    "0": "release_8bdd4190-4800-11e8-8887-cbf9f99d6f5d.json",
    "1": "release_0f506000-e870-11e6-9c33-0b00e23ebd5c.json"
  }
}
------WebKitFormBoundarywcYaMcsEONHWWBak--

Response #1 from the implementing server

{
  "missingFiles": [
    "release_8bdd4190-4800-11e8-8887-cbf9f99d6f5d.json",
    "latest.json"
  ]
}

POST #2 by promaster-edit

  • POST: http://target-server/publish
  • Content-Type: multipart/form-data; boundary=------WebKitFormBoundaryABjQr2vBCBbWviLB
------WebKitFormBoundaryABjQr2vBCBbWviLB
Content-Disposition: form-data; name="file"; filename="release_8bdd4190-4800-11e8-8887-cbf9f99d6f5d.json"
Content-Type: application/json

{
  "data": {
    "id": "8bdd4190-4800-11e8-8887-cbf9f99d6f5d",
    "name": "MyRelease",
    "products": {
      "b51d1bd0-20f0-11e8-932a-53b2ed4666ec": 0,
      "f13d06a0-d2d0-11e7-f503-afde08f276e6": 1
    }
  },
  "refs": {
    "0": "product_b51d1bd0-20f0-11e8-932a-53b2ed4666ec;486982.json",
    "1": "product_f13d06a0-d2d0-11e7-f503-afde08f276e6;445429.json"
  }
}
------WebKitFormBoundaryABjQr2vBCBbWviLB
Content-Disposition: form-data; name="file"; filename="release_0f506000-e870-11e6-9c33-0b00e23ebd5c.json"
Content-Type: application/json

{
  "data": {
    "id": "0f506000-e870-11e6-9c33-0b00e23ebd5c",
    "name": "MyOtherRelease",
    "products": {
      "b7306340-e870-11e6-8cec-7fa8b023db7f": 0,
      "12458d40-e870-11e6-b5f5-cb037dd1177a": 1,
      "272f7fb0-e870-11e6-a93e-65f84649c1b3": 2,
      "56740db0-e870-11e6-b520-e1b5c97d27ee": 3
    }
  },
  "refs": {
    "0": "product_b7306340-e870-11e6-8cec-7fa8b023db7f;225265.json",
    "1": "product_12458d40-e870-11e6-b5f5-cb037dd1177a;234093.json",
    "2": "product_272f7fb0-e870-11e6-a93e-65f84649c1b3;250777.json",
    "3": "product_56740db0-e870-11e6-b520-e1b5c97d27ee;231571.json"
  }
}
------WebKitFormBoundaryABjQr2vBCBbWviLB--

Response #2 from the implementing server

{
  "missingFiles": []
}

Reference implementations

There are reference implementations available in javascript for use in Koa. They are published as the @promaster/api-server package.