update refs and doc

doc/release-notes.md

@@ -6,6 +6,9 @@ Ziti 0.15.0 includes the following:
 * Remove deprecated AppWan and Clusters - These have been replaced by service policies and service edge router policies respectively
 * cosmetic changes to the ziti-enroller binary
 * cosmetic changes to the ziti-tunnel binary when running the enroll subcommand
+* Edge REST API Enhancements
+  * [OpenApi 2.0/Swagger](https://github.com/openziti/edge/issues/108)
+  * [Changes to support Fabric REST API](https://github.com/openziti/edge/issues/101)
 
 ## Removal of deprecated code
 The code to migrate a Ziti instance from pre-0.9 releases has been removed. If you want to migrate from a pre-0.9 version you should first update to 0.14.12, then to new versions.
@@ -17,6 +20,155 @@ The ziti-fabric tool can now be used to trigger the creation of a dabase backup/
 
 This will create a copy of the database file within a bolt transaction. The file name will have the data and time appended to it. Snapshotting can be done at most once per minute. Support to trigger this from the Edge REST API will be comming in a follow-up release.
 
+### Edge REST API Enhancements
+
+The v0.15.0 brings in new Edge REST API changes that are being made in
+preparation for future enhancements. Please read these changes carefully
+and adopt new patterns to avoid future incompatibility issues.
+
+#### OpenApi 2.0/Swagger
+
+The REST presentation of the Edge REST API is now fully generated from
+the Open API 2.0/Swagger specification in `edge/spec`. The the generated
+code is in `edge/rest_model`, `edge/rest_server`, and
+`edge_rest_client`. The code is generated by installing `go-swagger`,
+currently at version 0.24.0.
+
+The generated code introduces a few changes that may impact clients:
+
+*  `content-type` and `accept` headers are now meaningful and important
+*  enrollment endpoints can return JSON if JSON is explicitly set in
+`accept` headers
+*  API input validation errors
+*  various entity ref bugs
+*  standardization of id properties
+
+#### Content Type / Accept Headers
+
+For `content-type` and `accept` headers, if `accept` is not being set,
+clients usually send an `accept` of `*/*` - accepting anything. If so,
+the Edge REST API will continue to return `content-type`s that are the
+same as previous versions. However, non-JSON responses from enrollment
+endpoints are now deprecated.
+
+If a client is setting the `accept` header to anything other than
+`application/json` for most endpoints, the API will return errors
+stating the that the content types are not acceptable.
+
+#### API Input Validation
+
+API input validation is now handled by the Open API libraries and
+go-swagger generated code. The error formats returned are largely the
+same. However validations errors now all return the same outer
+error and set the cause error properly. Prior to this change
+errors were handled in an inconsistent manner.
+
+#### Entity Ref Bugs
+
+Various entity references were fixed where URLs were pointing to the
+wrong or invalid API URLs.
+
+#### Id Properties
+
+Id properties are now fully typed: <type>Id, in API request/responses.
+
+Entities affected:
+* config
+  * `type` to `configTypeid`
+* identity service config
+  * `service` to `serviceId`
+  * `config` to `configId`
+
+`IdentityTypeId` references were not updated as they are slated for
+removal and are now deprecated. This includes `/identity-type` and
+associated `/identity` properties for create/update/patch operations.
+
+### Changes to support Fabric REST API
+
+The following changes were done to support the future Fabric REST API
+
+* Edge REST API base moved to `/edge/v1`
+* `apiVersions` was introduced to `GET /versions`
+* move away from UUID formats for ids to shortIds
+
+#### Base Path
+
+The Edge REST API now has a base path of `edge/v1`. The previous base
+path, `/`, is now deprecated but remains active till a later release.
+This move is to create room for the Fabric REST API to take over the
+root path and allow other components to register APIs.
+
+#### API Versions
+
+For now the `GET /versions` functionality is handled by the Edge REST
+API but will be subsumed by a future Fabric REST API.
+
+The `GET /versions` now reports version information in a map structure
+such that future REST APIs, as they are introduced, can register
+supported versions. It is the goal of the Ziti REST APIs to support
+multiple API versions for backwards comparability.
+
+Example `GET /versions` response:
+
+```
+{
+    "data": {
+        "apiVersions": {
+            "edge": {
+                "v1": {
+                    "path": "/edge/v1"
+                }
+            }
+        },
+        "buildDate": "2020-06-11 16:03:13",
+        "revision": "95e78d4bc64b",
+        "runtimeVersion": "go1.14.3",
+        "version": "v0.15.0"
+    },
+    "meta": {}
+}
+```
+
+Example of a theoretical future version with the Fabric REST API:
+
+```
+{
+    "data": {
+        "apiVersions": {
+            "edge": {
+                "v1": {
+                    "path": "/edge/v1"
+                }
+            }
+            "fabric": {
+                "v1": {
+                    "path": "/fabric/v1"
+                }
+            }
+        },
+        "buildDate": "2020-06-20 12:43:03",
+        "revision": "1a27ed4bc64b",
+        "runtimeVersion": "go1.14.3",
+        "version": "v0.15.10"
+    },
+    "meta": {}
+}
+```
+
+#### ShortIds
+
+The Edge REST API has used UUID and its associated UUID text format for
+all ids. In 0.15 and forward, `shortIds` will be used and their
+associated format.
+
+ * make ids more human human friendly (logs, visual comparison)
+ * consolidate on ids that look similar between Fabric and Edge entities
+ * maintain a high degree of uniqueness comparable to UUIDs
+
+All Ziti REST APIs will specify their ids as `strings`. If clients treat
+ids as opaque strings, then no comparability issues are expected. It is
+highly highly suggested that all clients follow this pattern.
+
 # Release 0.14.13
 Ziti 0.14.13 includes the following:
 

go.mod

@@ -25,10 +25,10 @@ require (
 	github.com/kardianos/osext v0.0.0-20190222173326-2bc1f35cddc0
 	github.com/keybase/go-ps v0.0.0-20190827175125-91aafc93ba19
 	github.com/michaelquigley/pfxlog v0.0.0-20190813191113-2be43bd0dccc
-	github.com/openziti/edge v0.14.37
-	github.com/openziti/fabric v0.11.41
-	github.com/openziti/foundation v0.11.4
-	github.com/openziti/sdk-golang v0.13.6
+	github.com/openziti/edge v0.14.45
+	github.com/openziti/fabric v0.11.43
+	github.com/openziti/foundation v0.11.7
+	github.com/openziti/sdk-golang v0.13.10
 	github.com/pborman/uuid v1.2.0
 	github.com/pkg/errors v0.9.1
 	github.com/rcrowley/go-metrics v0.0.0-20200313005456-10cdbea86bc0
@@ -40,7 +40,7 @@ require (
 	github.com/spf13/cobra v0.0.7
 	github.com/spf13/pflag v1.0.5
 	github.com/spf13/viper v1.5.0
-	github.com/stretchr/testify v1.5.1
+	github.com/stretchr/testify v1.6.1
 	github.com/urfave/negroni v1.0.0
 	golang.org/x/net v0.0.0-20200226121028-0de0cce0169b
 	google.golang.org/grpc v1.25.1

go.sum

@@ -205,6 +205,8 @@ github.com/google/go-cmp v0.4.0 h1:xsAVV57WRhGj6kEIi8ReJzQlHHqcBYCElAvkovg3B/4=
 github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.4.1 h1:/exdXoGamhu5ONeUJH0deniYLWYvQwW66yvlfiiKTu0=
 github.com/google/go-cmp v0.4.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.0 h1:/QaMHBdZ26BB3SSst0Iwl10Epc+xhTquomWX0oZEB6w=
+github.com/google/go-cmp v0.5.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/uuid v1.0.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/google/uuid v1.1.1 h1:Gkbcsh/GbpXz7lPftLA3P6TYMwjCLYm83jiFQZF/3gY=
 github.com/google/uuid v1.1.1/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
@@ -307,8 +309,8 @@ github.com/miekg/pkcs11 v1.0.3/go.mod h1:XsNlhZGX73bx86s2hdc/FuaLm2CPZJemRLMA+WT
 github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
 github.com/mitchellh/mapstructure v1.1.2 h1:fmNYVwqnSfB9mZU6OS2O6GsXM+wcskZDuKQzvN1EDeE=
 github.com/mitchellh/mapstructure v1.1.2/go.mod h1:FVVH3fgwuzCH5S8UJGiWEs2h04kUh9fWfEaFds41c1Y=
-github.com/mitchellh/mapstructure v1.3.1 h1:cCBH2gTD2K0OtLlv/Y5H01VQCqmlDxz30kS5Y5bqfLA=
-github.com/mitchellh/mapstructure v1.3.1/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/mitchellh/mapstructure v1.3.2 h1:mRS76wmkOn3KkKAyXDu42V+6ebnXWIztFSYGN7GeoRg=
+github.com/mitchellh/mapstructure v1.3.2/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
 github.com/montanaflynn/stats v0.0.0-20171201202039-1bf9dbcd8cbe/go.mod h1:wL8QJuTMNUDYhXwkmfOly8iTdp5TEcJFWZD2D7SIkUc=
 github.com/mwitkow/go-conntrack v0.0.0-20161129095857-cc309e4a2223/go.mod h1:qRWi+5nqEBWmkhHvq77mSJWrCKwh8bxhgT7d/eI7P4U=
 github.com/netfoundry/secretstream v0.1.1 h1:z6T7B5DuOtr9O+SmKaS9DzwOoGLYtgvyTzuPuR5FO7I=
@@ -319,20 +321,15 @@ github.com/onsi/ginkgo v1.7.0 h1:WSHQ+IS43OoUrWtD1/bbclrwK8TTH5hzp+umCiuxHgs=
 github.com/onsi/ginkgo v1.7.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
 github.com/onsi/gomega v1.4.3 h1:RE1xgDvH7imwFD45h+u2SgIfERHlS2yNG4DObb5BSKU=
 github.com/onsi/gomega v1.4.3/go.mod h1:ex+gbHU/CVuBBDIJjb2X0qEXbFg53c61hWP/1CpauHY=
-github.com/openziti/edge v0.14.37 h1:zEFk+Wow2Htcb9iTr3lAnWwfFs2PkwlgmVhGdXjo3Gw=
-github.com/openziti/edge v0.14.37/go.mod h1:/FD4nh2v1GAq6vsoEBRYfLKjyHSt+ouxu8pznfcEXVQ=
-github.com/openziti/fabric v0.11.40 h1:IebmkMrAa7R216cBd1ROhON5RgiPFm9TVyqo7a2Aknk=
-github.com/openziti/fabric v0.11.40/go.mod h1:LsIAeOvc0ygIPZ2QCuh2l/nWbt2pp2e431KAhNtixws=
-github.com/openziti/fabric v0.11.41 h1:9nF3r7K76hNngDqEr1WkC7bTSZP08hhPCjeyAmvWYfY=
-github.com/openziti/fabric v0.11.41/go.mod h1:5m9QZeM62MiHLo5/QyY121oRypPc9atu1W8DUzyhDpM=
-github.com/openziti/foundation v0.11.2 h1:h6jsPLDkNzH1WTVPb8MPaECgYqEwzlXFwLRFeO1Aojk=
-github.com/openziti/foundation v0.11.2/go.mod h1:E+z3Ne+G1IrApCxg/+kKLFg5hUubElHyylvfCLJg4fk=
-github.com/openziti/foundation v0.11.3/go.mod h1:E+z3Ne+G1IrApCxg/+kKLFg5hUubElHyylvfCLJg4fk=
-github.com/openziti/foundation v0.11.4 h1:3EZ+H1iJB/bdWnGTiQUoTQFp4vHYZ7oZWM2JkE7AQW4=
-github.com/openziti/foundation v0.11.4/go.mod h1:E+z3Ne+G1IrApCxg/+kKLFg5hUubElHyylvfCLJg4fk=
-github.com/openziti/sdk-golang v0.13.5/go.mod h1:SaHHvLkf4HnTqK4iOQmNmA23BsylRGc5Npb/x0g0hJc=
-github.com/openziti/sdk-golang v0.13.6 h1:wlO+VljW4pNXwY8tANLWBLOOM91oRoZHvlBtv7JBbBI=
-github.com/openziti/sdk-golang v0.13.6/go.mod h1:TM1BobbkOY7TOVMXlciKQJaZQlSgqap89MHi0AgmRMM=
+github.com/openziti/edge v0.14.45 h1:P/bUFsDVMj3Eh9Rbqk1O9EjxJz51iWAW51LFr/jGnxI=
+github.com/openziti/edge v0.14.45/go.mod h1:BMfLnzTjmdsZCudteTDEuZ2zO0Jv4oh5qBCwTssNo2o=
+github.com/openziti/fabric v0.11.43 h1:+EEo1xYossvXf7LDLcnw3cJxaZwh+k8ez/Ew9qBUd9s=
+github.com/openziti/fabric v0.11.43/go.mod h1:va9H0K20ugtCsMj8/1vdRAWsWlFdy1T+OEdXm0e1LW4=
+github.com/openziti/foundation v0.11.5/go.mod h1:jfnQ8WWFJGrDD2COPtQ/yX+gRlaiMdwUuXbvEBOpnLc=
+github.com/openziti/foundation v0.11.7 h1:Eb7jHhRsEo9rorwqUQce5SR/NCSqTmlMyVHd0JiGEb8=
+github.com/openziti/foundation v0.11.7/go.mod h1:Qdd7eCuTrpRwEeDbvYy89sFbEY4+J7OuX8UygxNBsvY=
+github.com/openziti/sdk-golang v0.13.10 h1:iLYvWVNvU2rMUITRXLiriwRnSNngioROVrjewv7QQZQ=
+github.com/openziti/sdk-golang v0.13.10/go.mod h1:jXBekQvK4B9+w/JwN0uE9AAorFuqbph36uFGZHSmwkw=
 github.com/orcaman/concurrent-map v0.0.0-20190826125027-8c72a8bb44f6 h1:lNCW6THrCKBiJBpz8kbVGjC7MgdCGKwuvBgc7LoD6sw=
 github.com/orcaman/concurrent-map v0.0.0-20190826125027-8c72a8bb44f6/go.mod h1:Lu3tH6HLW3feq74c2GC+jIMS/K2CFcDWnWD9XkenwhI=
 github.com/pborman/uuid v1.2.0 h1:J7Q5mO4ysT1dv8hyrUGHb9+ooztCXu1D8MY8DZYsu3g=
@@ -415,8 +412,12 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV
 github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.5.1 h1:nOGnQDM7FYENwehXlg/kFVnos3rEvtKTjRvOWSzb6H4=
 github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
+github.com/stretchr/testify v1.6.1 h1:hDPOHmpOpP40lSULcqw7IrRb/u7w6RpDC9399XyoNd0=
+github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/subosito/gotenv v1.2.0 h1:Slr1R9HxAlEKefgq5jn9U+DnETlIUa6HfgEzj0g5d7s=
 github.com/subosito/gotenv v1.2.0/go.mod h1:N0PQaV/YGNqwC0u51sEeR/aUtSLEXKX9iv69rRypqCw=
+github.com/teris-io/shortid v0.0.0-20171029131806-771a37caa5cf h1:Z2X3Os7oRzpdJ75iPqWZc0HeJWFYNCvKsfpQwFpRNTA=
+github.com/teris-io/shortid v0.0.0-20171029131806-771a37caa5cf/go.mod h1:M8agBzgqHIhgj7wEn9/0hJUZcrvt9VY+Ln+S1I5Mha0=
 github.com/tidwall/pretty v1.0.0 h1:HsD+QiTn7sK6flMKIvNmpqz1qrpP3Ps6jOKIKMooyg4=
 github.com/tidwall/pretty v1.0.0/go.mod h1:XNkn88O1ChpSDQmQeStsy+sBenx6DDtFZJxhVysOjyk=
 github.com/tmc/grpc-websocket-proxy v0.0.0-20190109142713-0ad062ec5ee5/go.mod h1:ncp9v5uamzpCO7NfCPTXjqaC+bZgJeR0sMTm6dMHP7U=
@@ -436,8 +437,8 @@ github.com/xeipuuv/gojsonschema v1.2.0/go.mod h1:anYRn/JVcOK2ZgGU+IjEV4nwlhoK5sQ
 github.com/xiang90/probing v0.0.0-20190116061207-43a291ad63a2/go.mod h1:UETIi67q53MR2AWcXfiuqkDkRtnGDLqkBTpCHuJHxtU=
 github.com/xordataexchange/crypt v0.0.3-0.20170626215501-b2862e3d0a77/go.mod h1:aYKd//L2LvnjZzWKhF00oedf4jCCReLcmhLdhm1A27Q=
 go.etcd.io/bbolt v1.3.2/go.mod h1:IbVyRI1SCnLcuJnV2u8VeU0CEYM7e686BmAb1XKL+uU=
-go.etcd.io/bbolt v1.3.4 h1:hi1bXHMVrlQh6WwxAy+qZCV/SYIlqo+Ushwdpa4tAKg=
-go.etcd.io/bbolt v1.3.4/go.mod h1:G5EMThwa9y8QZGBClrRx5EY+Yw9kAhnjy3bSjsnlVTQ=
+go.etcd.io/bbolt v1.3.5-0.20200615073812-232d8fc87f50 h1:ASw9n1EHMftwnP3Az4XW6e308+gNsrHzmdhd0Olz9Hs=
+go.etcd.io/bbolt v1.3.5-0.20200615073812-232d8fc87f50/go.mod h1:G5EMThwa9y8QZGBClrRx5EY+Yw9kAhnjy3bSjsnlVTQ=
 go.mongodb.org/mongo-driver v1.0.3/go.mod h1:u7ryQJ+DOzQmeO7zB6MHyr8jkEQvC8vH7qLUO4lqsUM=
 go.mongodb.org/mongo-driver v1.1.1/go.mod h1:u7ryQJ+DOzQmeO7zB6MHyr8jkEQvC8vH7qLUO4lqsUM=
 go.mongodb.org/mongo-driver v1.1.2/go.mod h1:u7ryQJ+DOzQmeO7zB6MHyr8jkEQvC8vH7qLUO4lqsUM=
@@ -521,6 +522,8 @@ golang.org/x/sys v0.0.0-20190924154521-2837fb4f24fe/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20191008105621-543471e840be/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200202164722-d101bd2416d5 h1:LfCXLvNmTYH9kEmVgqbnsWfruoXZIrh4YBgqVHtDvw0=
 golang.org/x/sys v0.0.0-20200202164722-d101bd2416d5/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200615200032-f1bc736245b1 h1:ogLJMz+qpzav7lGMh10LMvAkM/fAoGlaiiHYiFYdm80=
+golang.org/x/sys v0.0.0-20200615200032-f1bc736245b1/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/text v0.3.0 h1:g61tztE5qeGQ89tm6NTjjM9VPIm088od1l6aSorWRWg=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.2 h1:tW2bmiBqwgJj/UpqtC8EpXEZVYOwU0yG4iWbprSVAcs=
@@ -577,6 +580,8 @@ gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.3.0 h1:clyUAQHOM3G0M3f5vQj7LuJrETvjVot3Z5el9nffUtU=
 gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 rsc.io/goversion v1.2.0 h1:SPn+NLTiAG7w30IRK/DKp1BjvpWabYgxlLp/+kx5J8w=