All Topics

#1197 Public review of v5 HTTP API

Brian Frank Fri 21 Aug

As part of the Xeto and Haystack 5 effort, we have developed a new version of the HTTP protocol.

Please take a look at the design docs and let us know if you have feedback.

Overview

Features and goals for this new version:

Full backward compatibility at the same endpoint using the Xeto-Version HTTP header
Leverage Xeto functions to precisely capture parameter and return types for both built-in ops and extensible vendor specific ops. This allows exchanging arguments and results as plain JSON and decoding against their declared types, rather than self-describing envelopes.
Support a Swagger/OpenAPI schema from the Xeto definitions
Define a new JSON flavor we nicknamed "Jeto" which allows for a cleaner JSON encoding with full fidelity to the whole Xeto type system (complements the existing Hayson format)
Errors are now encoded as HTTP error status codes with a JSON body with typed Xeto spec for each error case
Support for existing encoding formats (Zinc, Hayson, v3 JSON, Trio, and CSV) plus Xeto itself and new Jeto JSON encoding
Defines the HTTP protocol for xeto.dev and third party network repositories to download/publish Xeto libs
Add OAuth as new authentication option (not defined yet)

Examples

Here is a simple example of the read operation in v4 Hayson:

POST /api/demo/read
Authorization: bearer authToken=web-xxxx
Content-Type: application/json

{
  "_kind": "grid",
  "meta": {"ver":"3.0"},
  "cols": [
    {"name":"id"}
  ],
  "rows":[
    {"id":{"_kind":"ref", "val":"321b01cf-f2055719", "dis":"A"}}
  ]
}

200 OK
Content-Type: application/json

{
  "_kind": "grid",
  "meta": {"ver":"3.0"},
  "cols": [
    {"name":"id"},
    {"name":"dis"},
    {"name":"site"},
    {"name":"geoCity"},
    {"name":"area"},
    {"name":"spec"}
  ],
  "rows":[
    {"id":{"_kind":"ref", "val":"321b01cf-f2055719", "dis":"A"},
     "dis":"A",
     "site":{"_kind":"marker"},
     "geoCity":"Richmond",
     "area":{"_kind":"number", "val":30000, "unit":"ft²"},
     "spec":{"_kind":"ref", "val":"ph::Site"}}
  ]
}

Here is the same call with the readById op in v5 Jeto:

POST /api/demo/readById
Authorization: bearer authToken=web-xxxx
Content-Type: application/json
Accept: application/json;box=none
Xeto-Version: 5

{"id":"321b01cf-f2055719"}

200 OK
Content-Type: application/json
Xeto-Version: 5

{
  "spec": "ph::Site",
  "id": "321b01cf-f2055719",
  "dis": "A",
  "site": "✓",
  "geoCity": "Richmond",
  "area": "30000ft²"
}