From 651ce665bca9353b288cd6252b49dfc8c09677b9 Mon Sep 17 00:00:00 2001 From: parodime Date: Wed, 11 Sep 2024 05:59:10 -0400 Subject: [PATCH] API version docs updt (#3120) --- docs/bridge/docs/rfq/API/API.md | 10 +++++++++ services/rfq/api/docs/docs.go | 36 +++++++++++++++++++++++++++--- services/rfq/api/docs/swagger.json | 36 +++++++++++++++++++++++++++--- services/rfq/api/docs/swagger.yaml | 20 +++++++++++++++++ services/rfq/api/rest/handler.go | 4 ++++ services/rfq/api/rest/server.go | 1 + 6 files changed, 101 insertions(+), 6 deletions(-) diff --git a/docs/bridge/docs/rfq/API/API.md b/docs/bridge/docs/rfq/API/API.md index 392f91e1c0..dfbc77ffe3 100644 --- a/docs/bridge/docs/rfq/API/API.md +++ b/docs/bridge/docs/rfq/API/API.md @@ -25,6 +25,16 @@ The RFQ API is a RESTful API that allows users to post quotes and read quotes. T Only Solvers should be writing to the API, end-users need only read from the `/quotes` endpoint. +**API Version Changes** + +An http response header "X-Api-Version" will be returned on each call response. + +Any systems that integrate with the API should use this header to detect version changes and perform appropriate follow-up actions & alerts. + +Upon a version change, [versions.go](https://github.com/synapsecns/sanguine/blob/master/services/rfq/api/rest/versions.go) can be referred to for further detail on the version including deprecation alerts, etc. + +Please note, while Synapse may choose to take additional steps to alert & advise on API changes through other communication channels, it will remain the responsibility of the API users & integrators to set up their own detection & notifications of version changes as they use these endpoints. Likewise, it will be their responsibility review the versions.go file, to research & understand how any changes may affect their integration, and to implement any necessary adjustments resulting from the API changes. + **Authentication** In accordance with [EIP-191](https://eips.ethereum.org/EIPS/eip-191), the RFQ API requires a signature to be sent with each request. The signature should be generated by the user's wallet and should be a valid signature of the message `rfq-api` with the user's private key. The signature should be sent in the `Authorization` header of the request. We provide a client stub/example implementation in go [here](https://pkg.go.dev/github.com/synapsecns/sanguine/services/rfq@v0.13.3/api/client). diff --git a/services/rfq/api/docs/docs.go b/services/rfq/api/docs/docs.go index c68a9eb52c..af06bfa449 100644 --- a/services/rfq/api/docs/docs.go +++ b/services/rfq/api/docs/docs.go @@ -41,7 +41,13 @@ const docTemplate = `{ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "headers": { + "X-Api-Version": { + "type": "string", + "description": "API Version Number - See docs for more info" + } + } } } } @@ -72,7 +78,13 @@ const docTemplate = `{ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "headers": { + "X-Api-Version": { + "type": "string", + "description": "API Version Number - See docs for more info" + } + } } } } @@ -98,6 +110,12 @@ const docTemplate = `{ "items": { "$ref": "#/definitions/model.GetContractsResponse" } + }, + "headers": { + "X-Api-Version": { + "type": "string", + "description": "API Version Number - See docs for more info" + } } } } @@ -156,6 +174,12 @@ const docTemplate = `{ "items": { "$ref": "#/definitions/model.GetQuoteResponse" } + }, + "headers": { + "X-Api-Version": { + "type": "string", + "description": "API Version Number - See docs for more info" + } } } } @@ -185,7 +209,13 @@ const docTemplate = `{ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "headers": { + "X-Api-Version": { + "type": "string", + "description": "API Version Number - See docs for more info" + } + } } } } diff --git a/services/rfq/api/docs/swagger.json b/services/rfq/api/docs/swagger.json index f6bdd6e25b..5d28bbf785 100644 --- a/services/rfq/api/docs/swagger.json +++ b/services/rfq/api/docs/swagger.json @@ -30,7 +30,13 @@ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "headers": { + "X-Api-Version": { + "type": "string", + "description": "API Version Number - See docs for more info" + } + } } } } @@ -61,7 +67,13 @@ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "headers": { + "X-Api-Version": { + "type": "string", + "description": "API Version Number - See docs for more info" + } + } } } } @@ -87,6 +99,12 @@ "items": { "$ref": "#/definitions/model.GetContractsResponse" } + }, + "headers": { + "X-Api-Version": { + "type": "string", + "description": "API Version Number - See docs for more info" + } } } } @@ -145,6 +163,12 @@ "items": { "$ref": "#/definitions/model.GetQuoteResponse" } + }, + "headers": { + "X-Api-Version": { + "type": "string", + "description": "API Version Number - See docs for more info" + } } } } @@ -174,7 +198,13 @@ ], "responses": { "200": { - "description": "OK" + "description": "OK", + "headers": { + "X-Api-Version": { + "type": "string", + "description": "API Version Number - See docs for more info" + } + } } } } diff --git a/services/rfq/api/docs/swagger.yaml b/services/rfq/api/docs/swagger.yaml index c39cace1ef..a8ddffdcc6 100644 --- a/services/rfq/api/docs/swagger.yaml +++ b/services/rfq/api/docs/swagger.yaml @@ -99,6 +99,10 @@ paths: responses: "200": description: OK + headers: + X-Api-Version: + description: API Version Number - See docs for more info + type: string summary: Relay ack tags: - ack @@ -119,6 +123,10 @@ paths: responses: "200": description: OK + headers: + X-Api-Version: + description: API Version Number - See docs for more info + type: string summary: Upsert quotes tags: - quotes @@ -132,6 +140,10 @@ paths: responses: "200": description: OK + headers: + X-Api-Version: + description: API Version Number - See docs for more info + type: string schema: items: $ref: '#/definitions/model.GetContractsResponse' @@ -170,6 +182,10 @@ paths: responses: "200": description: OK + headers: + X-Api-Version: + description: API Version Number - See docs for more info + type: string schema: items: $ref: '#/definitions/model.GetQuoteResponse' @@ -193,6 +209,10 @@ paths: responses: "200": description: OK + headers: + X-Api-Version: + description: API Version Number - See docs for more info + type: string summary: Upsert quote tags: - quotes diff --git a/services/rfq/api/rest/handler.go b/services/rfq/api/rest/handler.go index 4e2f61b802..2878fb4cb3 100644 --- a/services/rfq/api/rest/handler.go +++ b/services/rfq/api/rest/handler.go @@ -49,6 +49,7 @@ func APIVersionMiddleware(serverVersion string) gin.HandlerFunc { // @Accept json // @Produce json // @Success 200 +// @Header 200 {string} X-Api-Version "API Version Number - See docs for more info" // @Router /quotes [put]. func (h *Handler) ModifyQuote(c *gin.Context) { // Retrieve the request from context @@ -94,6 +95,7 @@ func (h *Handler) ModifyQuote(c *gin.Context) { // @Accept json // @Produce json // @Success 200 +// @Header 200 {string} X-Api-Version "API Version Number - See docs for more info" // @Router /bulk_quotes [put]. func (h *Handler) ModifyBulkQuotes(c *gin.Context) { // Retrieve the request from context @@ -176,6 +178,7 @@ func parseDBQuote(putRequest model.PutQuoteRequest, relayerAddr interface{}) (*d // @Accept json // @Produce json // @Success 200 {array} model.GetQuoteResponse +// @Header 200 {string} X-Api-Version "API Version Number - See docs for more info" // @Router /quotes [get]. func (h *Handler) GetQuotes(c *gin.Context) { originChainIDStr := c.Query("originChainID") @@ -240,6 +243,7 @@ func (h *Handler) GetQuotes(c *gin.Context) { // @Accept json // @Produce json // @Success 200 {array} model.GetContractsResponse +// @Header 200 {string} X-Api-Version "API Version Number - See docs for more info" // @Router /contracts [get]. func (h *Handler) GetContracts(c *gin.Context) { // Convert quotes from db model to api model diff --git a/services/rfq/api/rest/server.go b/services/rfq/api/rest/server.go index 3c961b65f3..a3a3b32a6f 100644 --- a/services/rfq/api/rest/server.go +++ b/services/rfq/api/rest/server.go @@ -330,6 +330,7 @@ func (r *QuoterAPIServer) checkRole(c *gin.Context, destChainID uint32) (address // @Accept json // @Produce json // @Success 200 +// @Header 200 {string} X-Api-Version "API Version Number - See docs for more info" // @Router /ack [put]. func (r *QuoterAPIServer) PutRelayAck(c *gin.Context) { req, exists := c.Get("putRequest")