Skip to content

Commit

Permalink
API version docs updt (#3120)
Browse files Browse the repository at this point in the history
  • Loading branch information
@parodime
parodime authored Sep 11, 2024
1 parent bf9e14b commit 651ce66
Show file tree
Hide file tree
Showing 6 changed files with 101 additions and 6 deletions.
10 changes: 10 additions & 0 deletions docs/bridge/docs/rfq/API/API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/[email protected]/api/client).
Expand Down
36 changes: 33 additions & 3 deletions services/rfq/api/docs/docs.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
}
}
}
Expand Down Expand Up @@ -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"
}
}
}
}
}
Expand All @@ -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"
}
}
}
}
Expand Down Expand Up @@ -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"
}
}
}
}
Expand Down Expand Up @@ -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"
}
}
}
}
}
Expand Down
36 changes: 33 additions & 3 deletions services/rfq/api/docs/swagger.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
}
}
}
Expand Down Expand Up @@ -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"
}
}
}
}
}
Expand All @@ -87,6 +99,12 @@
"items": {
"$ref": "#/definitions/model.GetContractsResponse"
}
},
"headers": {
"X-Api-Version": {
"type": "string",
"description": "API Version Number - See docs for more info"
}
}
}
}
Expand Down Expand Up @@ -145,6 +163,12 @@
"items": {
"$ref": "#/definitions/model.GetQuoteResponse"
}
},
"headers": {
"X-Api-Version": {
"type": "string",
"description": "API Version Number - See docs for more info"
}
}
}
}
Expand Down Expand Up @@ -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"
}
}
}
}
}
Expand Down
20 changes: 20 additions & 0 deletions services/rfq/api/docs/swagger.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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'
Expand Down Expand Up @@ -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'
Expand All @@ -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
Expand Down
4 changes: 4 additions & 0 deletions services/rfq/api/rest/handler.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions services/rfq/api/rest/server.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down

0 comments on commit 651ce66

Please sign in to comment.